Event payload and headers

Event payload structure

Webhook event payloads are JSON objects sent in the body of the HTTP POST request. While the data field varies by event type, the overall payload structure is the following:

Field	Type	Description
`type`	String	The type of the event. Example: `user.created`.
`timestamp`	Integer	The time the action occurred on your platform, in Unix epoch milliseconds.
`data`	Object	The data associated with the event. The structure of this object depends on the `type` of event.

Example:

{
  "type": "user.created",
  "timestamp": 1749816650724,
  "data": {
    "userId": "684c154ab06eb32565e5cbc0",
    "createdAt": "2025-06-13T12:10:50.568Z",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "mail": "[email protected]"
  }
}

Webhook request headers

Key HTTP headers are included with every webhook request. Use them to validate event security, maintain idempotency, and process events accurately.

Header	Description
`webhook-signature`	The signature of the event payload. Format:`v1,<signature>`. Example: `v1,4UHnozIIxoqswxyYsplgMpo1w5JaUjaPDlg5dm8n1SE=` If multiple signatures are present (e.g., during key rotation), they are separated by spaces. Use this header to verify the authenticity and integrity of the event. See Webhooks security and signature verification for details.
`webhook-id`	The unique identifier for the webhook event. This value remains the same across all retry attempts for the same event. Example: `msg_35bE2UOtsaBIqUl7VW4mLuR9q2B` Use this ID to implement idempotency and prevent the same event from being processed multiple times. See Webhooks processing best practices for details.
`webhook-timestamp`	The time the platform emitted the attempt, in Unix epoch seconds. Example: `1763370163` Use this timestamp to mitigate replay attacks in conjunction with the signature. See Webhooks processing best practices for details.

Header

Description

webhook-signature

The signature of the event payload. Format:v1,<signature>.
Example: v1,4UHnozIIxoqswxyYsplgMpo1w5JaUjaPDlg5dm8n1SE=

If multiple signatures are present (e.g., during key rotation), they are separated by spaces.

Use this header to verify the authenticity and integrity of the event. See Webhooks security and signature verification for details.

webhook-id

The unique identifier for the webhook event. This value remains the same across all retry attempts for the same event.
Example: msg_35bE2UOtsaBIqUl7VW4mLuR9q2B

Use this ID to implement idempotency and prevent the same event from being processed multiple times. See Webhooks processing best practices for details.

webhook-timestamp

The time the platform emitted the attempt, in Unix epoch seconds. Example: 1763370163

Use this timestamp to mitigate replay attacks in conjunction with the signature. See Webhooks processing best practices for details.