Webhook API reference
Webhooks provide an additional way to consume messages on a topic. When a webhook is created, it gets attached to a topic. When messages are published to this topic, an outbound http call gets POSTed to the webhook callback url. The endpoint that is associated with the webhook must be publicly accessible for Momento to be able to POST requests. To confirm receipt, your api should respond with an empty HTTP 2xx response to the original request. If confirmation is not received within 5 seconds, we drop the message and mark it as timed out.
All messages that are sent to the webhook are still available to be received with a subscription to the topic.
Put Webhook API
Generates a new webhook with the provided webhook.
Name | Type | Description |
---|---|---|
webhook | Webhook | The webhook object to be created. |
Method response object
- Success
secretString
: string - the signing secret for the webhook
- Error
See response objects for specific information.
Webhooks are essential for real-time updates and notifications. Make sure to securely store the secretString
provided
upon success, as it is required for validating incoming webhook requests.
Example
const webhookId: WebhookId = {
cacheName: 'exampleCache',
webhookName: 'exampleWebhook',
};
const result = await webhookClient.putWebhook(webhookId.cacheName, webhookId.webhookName, {
destination: new PostUrlWebhookDestination('https://example.com/webhook'),
topicName: 'exampleTopic',
});
if (result instanceof PutWebhook.Success) {
console.log('Webhook created successfully. Secret:', result.secret);
} else {
console.error('Error creating webhook:', result.error.message);
}
List Webhook API
Retrieves a list of webhooks for a specific cache.
Name | Type | Description |
---|---|---|
cache | string | The name of the cache to list webhooks for. |
Method response object
- Success
webhooks
: array of Webhook - the list of webhooks for the specified cache.
- Error
See response objects for specific information.
The List Webhook API can be called as frequently as needed to retrieve the latest list of webhooks. However, consider caching the results to reduce unnecessary API calls and improve performance.
Example
const cacheName: string = 'exampleCache';
const result = await webhookClient.listWebhooks(cacheName);
if (result instanceof ListWebhooks.Success) {
console.log('Webhooks retrieved successfully:', result.webhooks);
} else {
console.error('Error retrieving webhooks:', result.error.message);
}
Delete Webhook API
Deletes a webhook with the specified identifier.
Name | Type | Description |
---|---|---|
id | WebhookId | The unique identifier of the webhook to be deleted. |
Method response object
- Success
- No additional data on success.
- Error
See response objects for specific information.
When a webhook is deleted, it will no longer be active, and incoming requests to the deleted webhook will be ignored.
Example
const webhookId: WebhookId = {
cacheName: 'exampleCache',
webhookName: 'exampleWebhook',
};
const result = await webhookClient.deleteWebhook(webhookId.cacheName, webhookId.webhookName);
if (result instanceof DeleteWebhook.Success) {
console.log('Webhook deleted successfully');
} else {
console.error('Error deleting webhook:', result.error.message);
}
Get Webhook Secret API
Retrieves the secret string associated with a specific webhook.
Name | Type | Description |
---|---|---|
id | WebhookId | The unique identifier of the webhook to retrieve the secret for. |
Method response object
- Success
secret
: string - the signing secret for the webhook.webhookName
: string - the name of the webhook.cacheName
: string - the name of the cache associated with the webhook.
- Error
See response objects for specific information.
The signing secret is essential for validating incoming webhook requests. Ensure to securely store and manage the retrieved secret.
Example
const webhookId: WebhookId = {
cacheName: 'exampleCache',
webhookName: 'exampleWebhook',
};
const result = await webhookClient.getWebhookSecret(webhookId.cacheName, webhookId.webhookName);
if (result instanceof GetWebhookSecret.Success) {
console.log('Webhook secret retrieved successfully:', result.secret);
} else {
console.error('Error retrieving webhook secret:', result.error.message);
}
Rotate Webhook Secret API
Rotates the signing secret used for the webhook. Once the secret is rotated, all new POST requests sent to the webhook endpoint will have a 'momento-signature' header signed with the new secret.
Name | Type | Description |
---|---|---|
id | WebhookId | The unique identifier of the webhook to rotate the secret for. |
Method response object
- Success
secret
: string - the new signing secret for the webhook.webhookName
: string - the name of the webhook.cacheName
: string - the name of the cache associated with the webhook.
- Error
See response objects for specific information.
Secret rotation cannot be reverted, it is important to update all webhooks that are validating requests against a previous secret.
Example
const webhookId: WebhookId = {
cacheName: 'exampleCache',
webhookName: 'exampleWebhook',
};
const result = await webhookClient.rotateWebhookSecret(webhookId.cacheName, webhookId.webhookName);
if (result instanceof RotateWebhookSecret.Success) {
console.log('Webhook secret rotated successfully:', result.secret);
} else {
console.error('Error rotating webhook secret:', result.error.message);
}
Webhook object
The Webhook
object contains the necessary information to create a webhook.
Name | Type | Description |
---|---|---|
id | WebhookId | The unique identifier for the webhook. |
destination | WebhookDestination | The destination where the webhook payload will be sent. Must be publicy accessible. |
topicName | string | The name of the topic to which the webhook is subscribed. |
WebhookId object
The WebhookId
object represents the unique identifier of a webhook.
Name | Type | Description |
---|---|---|
cacheName | string | The name of the cache associated with the webhook. |
webhookName | string | The name of the webhook. |
WebhookDestination object
The WebhookDestination
object contains the information about where the webhook payload will be sent.
Name | Type | Description |
---|---|---|
postUrl | string | The URL to which the payload will be sent using HTTP POST. |
FAQ
How do I validate incoming webhook requests?
Check out our webhook security page on validating inbound webhook requests.
What is the structure of the POST body?
{
cache: string;
topic: string;
event_timestamp: number;
publish_timestamp: number;
topic_sequence_number: number;
token_id: string; // is an empty string if the message was published with an api key that does not contain a token_id
text: string; // this is the message that was published
}
What should I do if the webhook subscription fails?
Ensure that your webhook url is public and valid. Common issues include wrong cache or topic names, or issues with the provided postUrl
.
If you have any questions not answered here, please reach out on our Discord server and ask our experts in the support channel.