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.

note

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.

note

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

JavaScript

const result = await topicClient.putWebhook(cacheName, 'examples webhook', {
  topicName: 'a topic',
  destination: 'https://www.thisisawebhookurl.com/v1/webhook',
});
switch (result.type) {
  case PutWebhookResponse.Success:
    console.log('Successfully put webhook');
    break;
  case PutWebhookResponse.Error:
    throw new Error(
      `An error occurred while attempting to put the webhook 'examples webhook' inside of cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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.

note

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

JavaScript

const result = await topicClient.listWebhooks(cacheName);
switch (result.type) {
  case ListWebhooksResponse.Success:
    console.log(`Listed webhooks for cache '${cacheName}': ${result.getWebhooks()}`);
    break;
  case ListWebhooksResponse.Error:
    throw new Error(
      `An error occurred while attempting to list webhooks for cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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.

note

When a webhook is deleted, it will no longer be active, and incoming requests to the deleted webhook will be ignored.

Example

JavaScript

const result = await topicClient.deleteWebhook(cacheName, 'examples webhook');
switch (result.type) {
  case DeleteWebhookResponse.Success:
    console.log('Successfully deleted webhook');
    break;
  case DeleteWebhookResponse.Error:
    throw new Error(
      `An error occurred while attempting to delete webhook 'examples webhook' inside of cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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.

note

The signing secret is essential for validating incoming webhook requests. Ensure to securely store and manage the retrieved secret.

Example

JavaScript

const result = await topicClient.getWebhookSecret(cacheName, 'examples webhook');
switch (result.type) {
  case GetWebhookSecretResponse.Success:
    console.log(`Successfully retrieved the webhook secret: ${result.secret()}`);
    break;
  case GetWebhookSecretResponse.Error:
    throw new Error(
      `An error occurred while attempting to get the secret for the webhook 'examples webhook' inside of cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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.

note

Secret rotation cannot be reverted, it is important to update all webhooks that are validating requests against a previous secret.

Example

JavaScript

const result = await topicClient.rotateWebhookSecret(cacheName, 'examples webhook');
switch (result.type) {
  case RotateWebhookSecretResponse.Success:
    console.log('Successfully rotated the webhook secret');
    break;
  case RotateWebhookSecretResponse.Error:
    throw new Error(
      `An error occurred while attempting to rotate the secret for the webhook 'examples webhook' inside of cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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.