The API can also be authenticated using a per tenant token that’s valid for 24 hours. When using the a JWT token the /:tenant_id of each API endpoints is inferred to be the authenticated token and is not necessary.
The API segments resources per tenant. A tenant represents a user/team/organization in your product. The provided value determines the tenant's ID, which can be any string representation.
If your system is not multi-tenant, create a single tenant with a hard-code tenant ID upon initialization. If your system has a single tenant but multiple environments, create a tenant per environment, like live and test.
{ "id": "123", //User-defined system ID "destinations_count": 5, // Integer "topics": ["user.created", "user.deleted"], // List of subscribed topics across all destinations "created_at": "2024-01-01T00:00:00Z" // ISO Date}
{ "id": "des_12345", // Control plane generated ID or user provided ID "type": "webhooks", // Type of the destination "topics": ["user.created", "user.updated"], // Topics of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks/user" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "some***********" }, "delivery_metadata": { // Optional. Static key-value pairs automatically merged into event metadata on every delivery "x-api-key": "sk_live_abc123", "x-tenant-id": "tenant_456" }, "metadata": { // Optional. Arbitrary contextual information stored with the destination "name": "Production Webhook Server", "description": "Main webhook endpoint for order processing" }, "disabled_at": null, // null or ISO date if disabled "created_at": "2024-01-01T00:00:00Z" // Date the destination was created}
topics: Can contain either a list of topics or a wildcard * implying that all topics are supported. If you do not wish to implement topics for your application, set all destination topics to *.
credentials (optional): By default all destination credentials are obfuscated and the values cannot be read. This does not apply to the webhook type destination secret—each destination type can expose their own obfuscation logic.
delivery_metadata (optional): Static key-value pairs automatically merged into event metadata on every delivery. Values are encrypted like credentials. Useful for destination-specific metadata like API keys, authentication tokens, tenant identifiers, or any custom headers/attributes required by the receiving service. For webhook destinations, these are translated to HTTP headers. The merge priority is: system metadata (event-id, topic, timestamp) < delivery_metadata < event metadata.
metadata (optional): Arbitrary contextual information stored with the destination for organizational purposes (e.g., name, description, notes). Not encrypted and not included in event deliveries. Useful for documenting what a destination is used for or adding labels for filtering.
Return a list of the destinations. The endpoint is not paged, and the maximum number is equivalent to the maximum configured number of destinations per tenant through the MAX_DESTINATIONS_PER_TENANT env variable.
[ { "id": "dest_123456", // Control plane generated ID or user provided ID "type": "webhooks", // Type of the destination "topics": ["user.created", "user.updated"], // Type of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks/user" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "something-super-secret" }, "created_at": "2024-01-01T00:00:00Z" // Date the destination was created }]
{ "id": "123", // Optional, UUID will be generated if empty "type": "webhooks", // String of valid destination type "topics": "*", // '*' or String[] of enabled topics, "*" for all "config": { // Config object for the given type "url": "https://example.com/webhooks" }, "credentials": null // Credentials for the given type. It can be empty or null.}
{ "id": "des_12345", // ID of the destination "type": "webhooks", // Type of the destination "topics": ["*"], // Topics of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "some************" }, "disabled_at": null, // null or ISO date if disabled "created_at": "2024-01-01T00:00:00Z" // Date the destination was created}
Webhook secrets and rotations are a special case for the webhook destination type. The destination type credentials.secret is only a valid input when using the Admin API and can be omited when a secret is generated automatically.
Additionally, credentials.previous_secret can be used to set a rotated secret during a migration. credentials.rotate_secret can be used to automatically rotate the existing secret which results in a new credentials.secret and credentials.previous_secret value.
previous_secret are valid and used to “double” sign the request for 24 hours.
{ "type": "webhooks", // Optional. String of valid destination type "topics": "*", // Optional. String[] of enabled topics, "*" for all "config": { // Optional. Config object for the given type "url": "https://example.com/webhooks" }, "credentials": null // Optional. Credentials for the given type. It can be empty or null.}
{ "id": "des_12345", // Control plane generated ID "type": "webhooks", // Type of the destination "topics": "*", // Topics of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "some********" }, "disabled_at": null, // null or ISO date if disabled "created_at": "2024-01-01T00:00:00Z" // Date the destination was created}
{ "id": "des_12345", // Control plane generated ID "type": "webhooks", // Type of the destination "topics": "*", // Topics of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "some************" }, "disabled_at": null, // null or ISO date if disabled "created_at": "2024-01-01T00:00:00Z" // Date the destination was created}
{ "id": "des_12345", // Control plane generated ID "type": "webhooks", // Type of the destination "topics": "*", // Topics of events this destination is eligible for "config": { // Destination type specific configuration. Schema of depends on type "url": "https://example.com/webhooks" }, "credentials": { // Destination type specific credentials. AES encrypted. Schema depends on type "secret": "some***********" }, "disabled_at": "2024-01-01T00:00:00Z", // null or ISO date if disabled "created_at": "2024-01-01T00:00:00Z" // Date the destination was created}
{ "tenant_id": "<TENANT_ID>", "destination_id": "<DESTINATION_ID>", // Optional. Provide a way of routing events to a specific destination "topic": "topic.name", // Topic defined in TOPICS environment variable "eligible_for_retry": true | false, // Should event delivery be retried "metadata": Payload, // can by any JSON payload, "data": Payload // can by any JSON payload}
