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.
Example event
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.
{
"cache": "chat",
"topic": "room-281",
"event_timestamp": 1704296470564,
"publish_timestamp": 1704296470565,
"topic_sequence_number": 1,
"token_id": "mo-the-squirrel",
"text": "Here I am!!"
}
Event structure
The properties of the webhook event are listed below along with the function they provide.
cache
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.
topic
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.
event_timestamp
Timestamp in milliseconds since the Unix Epoch when the event was published.
publish_timestamp
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.
topic_sequence_number
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.
token_id
Unique identifier from a token. When a token is created via the Momento AuthClient, you can provide an identifier to be passed along all events published to Momento Topics. Learn more.
text
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.
Headers
Each request includes two specific headers provided by Momento, enabling integrators to verify the sender's authenticity.
Momento-Signature
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.
User-Agent
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).
Event delivery
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.