List Outbound Webhooks
/v1/outbound-webhooksorg.outbound_webhooksorg.permission.outbound_webhook.readorg.admin.outbound_webhooksThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Fetches outbound web hooks.
Outbound webhooks
An outbound webhook is a subscription that tells Kustomer to send certain events, such as a new conversation or an updated customer, to your HTTPS endpoint as they happen. Transactions are the log of recent delivery attempts, used to debug failures.
An outbound webhook pairs a url with a list of events. Whenever one of those events happens in your org, Kustomer sends the event envelope to the URL as a signed JSON POST. This is the opposite direction from inbound hooks, which are Kustomer-hosted addresses that receive your data. Admins manage webhooks in Settings › Platform › Outbound webhooks, and apps can create them at install time through the outboundWebhooks section of an app definition. A webhook keeps delivering until you disable or delete it, or until Kustomer disables it because your endpoint keeps failing.
Key fields
| Field | Meaning |
|---|---|
name |
Display name, up to 255 characters |
url |
Your endpoint. It must use https://. |
events |
Up to 12 event names, such as kustomer.conversation.update. GET /v1/outbound-webhooks/events lists the ones you can subscribe to. |
headers |
Extra { name, value } headers sent with every delivery, such as a shared secret your gateway checks |
enabled |
Whether Kustomer sends deliveries. Defaults to true. |
isError |
true when Kustomer has disabled the webhook automatically after sustained failures |
token |
The secret Kustomer uses to sign each delivery |
Signing and delivery
Each delivery has an X-Kustomer-Webhook-Signature header: the hex HMAC-SHA256 of the raw request body, keyed with the webhook's token. Verify it before trusting the body. Delivery is at least once and not ordered, so deduplicate on the event id and ignore snapshots older than the one you have. Kustomer retries failed deliveries for a while, then drops the event. If failures continue, it sets enabled to false and isError to true, and events that happen while a webhook is off are not queued for later. See Delivery and security for the retry schedule and how to reconcile after an outage.
Transactions
A transaction is the record of one delivery attempt. It holds the webhookId, the eventName sent, sentAt (a millisecond timestamp), status (succeeded or failed) and nextRetry, the millisecond timestamp of the next attempt, which is null once the event succeeded or ran out of attempts. Transactions don't include the payload. Only the 25 most recent attempts are returned, for one webhook or across all of them, so treat them as a debugging view rather than an audit trail.
Which endpoint to use
| To | Call |
|---|---|
| Find the events you can subscribe to | GET /v1/outbound-webhooks/events |
| Create a webhook | POST /v1/outbound-webhooks |
| List webhooks | GET /v1/outbound-webhooks |
Read one webhook, including its token |
GET /v1/outbound-webhooks/{id} |
| Change the URL, events or headers, or pause and re-enable it | PATCH /v1/outbound-webhooks/{id} |
| Delete a webhook | DELETE /v1/outbound-webhooks/{id} |
| See recent delivery attempts for one webhook | GET /v1/outbound-webhooks/{webhookId}/transactions |
| See recent delivery attempts across all webhooks | GET /v1/outbound-webhooks/transactions |
How many webhooks an org can have depends on its plan; creating one beyond the limit fails with 409 Conflict. There is no endpoint to rotate a token: create a second webhook with the same URL and events, accept both tokens while you switch, then delete the old one. After re-enabling a webhook with PATCH { "enabled": true }, reconcile anything you missed with incremental search. Each endpoint accepts the matching outbound webhook permission, such as org.permission.outbound_webhook.create for creating, or the outbound webhooks admin role.
Query parameters
Filter app-installed resources by app-disabled status.
falseAdditional outbound webhook filters.
{"events":"kustomer.conversation.create"}Return outbound webhooks with IDs greater than this value.
"5f3a9a562b3fc60013f5d756"Responses
Success