Kustoms Webhooks allow you to receive real-time notifications when events occur in our system. Instead of polling the API, you configure an endpoint and Kustom will send an HTTP POST request to that URL whenever a subscribed event occurs. We're planning to add additional delivery mechanisms as well at a later point.
Webhook payloads are intentionally slim. They contain just enough information to identify that something has happened. To get the most up to date information, use the included identifiers to fetch the full object from the relevant API endpoint.
Create an HTTPS endpoint on your server that:
- Accepts
POSTrequests - Returns a
2xxHTTP status code to acknowledge receipt - Responds within a reasonable timeout
If your endpoint does not return a 2xx response, Kustom will retry delivery (see Retries).
Configure your webhook destination in the Kustom Portal under Settings → Webhooks. There you can decide what HTTPS endpoint to use and which events to listen to.
Every webhook request includes signature headers so you can verify the payload originated from Kustom. See Security & Signature Verification below.
The following event types are supported:
| Event type | Description |
|---|---|
dispute.created | A new dispute has been opened on an order. |
dispute.updated | An existing dispute has been updated (e.g. status change). |
order.created | A new order has been created. |
capture.created | A capture has been made on an order. |
refund.created | A refund has been issued on an order. |
All webhook payloads follow a consistent structure:
{
"id": "kevt_1YcaJdWrmlw9yp1GiiVgad",
"merchant_id": "DM11917000",
"timestamp": "2026-04-10T08:27:07.248645321Z",
"type": "capture.created",
"data": {
"order_id": "25ed76ed-6477-46bb-8444-63945789ccfb",
"capture_id": "070ddfa9-f7a8-4fb0-8291-b5b31a300a23",
"created_at": "2026-04-10T08:27:02.648627Z"
}
}Fields:
id— A unique ID for this event. Stable across retries — use this for idempotency.merchant_id— Your Kustom Merchant ID (MID).type— The type of event that occurred.timestamp— ISO 8601 timestamp of when the event was generated.
Additional fields vary by event type (e.g. order_id, dispute_id, status).
To retrieve the full object, use the relevant API endpoint with the provided identifier.
Kustom signs every webhook payload so you can confirm it was sent by Kustom and has not been tampered with. We follow the Standard Webhooks specification.
Every webhook request includes three headers:
| Header | Description |
|---|---|
webhook-id | A unique message ID. Identical across retry attempts — use for deduplication. |
webhook-timestamp | Unix timestamp (seconds) of when the message was sent. |
webhook-signature | One or more HMAC-SHA256 signatures, space-delimited (for key rotation support). |
When you configure a webhook destination, Kustom generates a shared signing secret in the format:
whsec_<base64-encoded-secret>
You can retrieve and rotate this secret via the Portal.
More information and best practices on verifying the signature can be found in Standard Webhooks documentation.
You can rotate your signing secret at any time via the Portal. The rotation can take up to 10 mins to as it's reliant on caching. During a rotation period, Kustom will sign with both the old and new secrets (space-delimited in webhook-signature). Once you have updated your code to use the new secret, you can retire the old one.
If your endpoint does not respond with a 2xx status code, or times out, Kustom will retry delivery automatically using an exponential backoff strategy. Retries continue for up to 3 days.
Because events may be delivered more than once (e.g. during retries), your endpoint should be idempotent. Use the id (or webhook-id header) to detect and safely discard duplicate deliveries.