Use webhooks as subscribers to a topic
Trigger endpoints in your application when a message is published to a topic. Every time an event is published, Momento will send a POST request to all configured webhooks and any other subscribers.
Why use webhooks?
When using the Momento SDK to subscribe to a topic, a persistent connection is setup between your application code and the Momento service. This makes a standard subscription stateful, meaning the subscriber must always be on and available in order to publish or receive messages. Subscribers like browsers and containers work incredibly well in this environment, but it leaves stateless compute like Lambda functions or Google Cloud Run services out of luck.
Webhooks allow you to subscribe any type of compute to receive events. Since a webhook does not maintain an active connection, you can put a serverless function behind an endpoint and be on your merry way!
Using a webhook as a subscriber is perfect for asynchronous events like persisting messages to durable storage like a database, replicating data across regions, and even adding intermediary services like translation and moderation to chats.
A topic can have both stateful subscriptions and webhooks. This allows you to connect anything you want, from anywhere, at any time!
The webhook event
When an event is published to a topic, Momento will generate a request that includes metadata about the event in addition to the event payload. For enhanced security, this request includes additional headers.
Below is a sample payload representing a message sent in a chat room. Note that this is a template and specific values will differ in your implementation.
"text": "Here I am!!"
The properties of the webhook event are listed below along with the function they provide.
The name of the cache the topic belongs to. This is used for namespacing purposes in Momento Topics. All topics must be published to a valid cache in your account.
The name of the topic that triggered the webhook. Remember, topic names are dynamic and are not resources in your Momento account. You can publish a message to any string, which adds an incredible amount of flexibility to messages, like using a variable as the topic name of your workflow.
Timestamp in milliseconds since the Unix Epoch when the event was published.
Timestamp in milliseconds since the Unix Epoch when the webhook was published to. You can subtract the
event_timestamp value from this value to determine the server side latency for message delivery. In our example above, the delivery latency was 1 millisecond.
Message number for the topic. As messages are published, the
topic_sequence_number increments. This can be used for determining order. After a period of inactivity, the sequence numbers will reset back to 0. Momento does not guarantee order for event delivery.
The contents of the event published to the topic. The contents of this property are provided by the publisher and are not generated by Momento.
Each request includes two specific headers provided by Momento, enabling integrators to verify the sender's authenticity.
A signature of the request payload, signed with the secret you specified when setting up your webhook, used to verify the integrity and origin of the request. Check out our webhook security page on validating inbound requests.
A static header sent by Momento to identify the source of the request, with the format
Momento/1.0 (Webhooks; +https://docs.momentohq.com/topics/webhooks).
Momento will attempt to deliver an event to your webhook one time. If an event is not received by your endpoint, the publisher is required to send the message again.
A failed delivery, which will not be redriven automatically, could be due to one of the following reasons:
- A non-2XX response (e.g., 400, 403, 500, etc.).
- No response after 5 seconds.
- A connection error to your endpoint.
- Rate limit exceeded (see default limits).
API calls for Webhooks
Interested in using our SDKs to programmatically setup webhooks? See our API reference page for webhooks.