> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sezzle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Signature, Acceptance and Retries
## Webhook Signature
* Secured with HMAC-SHA256 signature.
* Sezzle-Signature header contains a hash of the webhook body, generated using the merchant private key.
* Always verify the signature matches the webhook data to confirm it originates from Sezzle.
## Webhook Delivery and Network
* Webhooks are server-to-server HTTP POST requests sent from Sezzle's infrastructure directly to your endpoint.
* They do not originate from a browser or from a resolvable Sezzle hostname, so there is no domain to add to an allowlist.
* Requests carry a standard server-side user-agent and none of the headers a browser sends, such as cookies, `Referer`, or `Accept-Language`. Bot-mitigation rules on some WAF and CDN products score requests on those signals and may block deliveries.
If your endpoint sits behind a security product, we recommend exempting your webhook path from bot rules, then verifying the `Sezzle-Signature` header in your application as described above.
These are two separate steps. A rule that admits any request carrying a `Sezzle-Signature` header does not authenticate anything on its own, since any caller can set that header to any value. The security comes from recomputing the HMAC over the request body with your private key and rejecting requests whose signature does not match. Done that way, signature verification confirms an event genuinely came from Sezzle, which source-IP filtering alone cannot do.
If your security policy requires a source IP allowlist, contact your Account Manager. Our egress addresses are not published here so that we can notify affected merchants directly ahead of any infrastructure change.
## Webhook Event Payload
Unique identifier for the webhook event.
Timestamp (ISO 8601) when the event was generated.
Type of the event
Available options: `customer.tokenized`, `order.authorized`, `order.captured`, `order.refunded`, `dispute.merchant_input_requested`, `dispute.deadline_approaching`, `dispute.closed.customer_win`, `dispute.closed.merchant_win`, `dispute.closed.neutral`
Type of data associated with the event.
Available options: `customer`, `order`, `dispute`
Payload data specific to the event type. See options in the applicable accordion below.
```json theme={"system"}
{
"uuid": string,
"created_at": string,
"event": string,
"data_type": string,
"data": {
"token": string,
"expiration": string,
"customer": {
"uuid": string,
"created_at": string,
"expiration": string
}
}
}
```
### Examples per Event
```json theme={"system"}
{
"uuid": "e41c32d5-687d-414f-b5c6-d089bea52e7d",
"created_at": "2025-04-12T00:11:01.749261Z",
"event": "customer.tokenized",
"data_type": "tokenize",
"data": {
"token": "ce56604a-5dfd-489a-80e9-753d0325dd46",
"expiration": "2025-04-12T00:41:01.745145Z",
"customer": {
"uuid": "e0003e6a-7234-4440-9265-61906e8b8879",
"created_at": "2025-04-12T00:11:01.745145Z",
"expiration": "2026-04-12T00:11:01.745145Z"
}
}
}
```
* The `"uuid"` is the webhook UUID
* The `"data.uuid"` is the order UUID that can be used on the API call to get order details
* The `"data.authorization.uuid"` is the UUID for the authorization
```json theme={"system"}
{
"uuid": "fdb263a1-a1dd-4feb-8749-c8a447977ebb",
"created_at": "2025-04-12T00:15:39.281826Z",
"event": "order.authorized",
"data_type": "order",
"data": {
"uuid": "f36605a0-4a96-46d1-9d01-a0b17140dc57",
"authorization": {
"uuid": "28ef487d-8398-43bb-8354-5ebdd1eb7b40",
"created_at": "2025-04-12T00:15:39.276841Z",
"authorization_amount": {
"amount_in_cents": 5000,
"currency": "USD"
},
"approved": true,
"expiration": "2025-04-12T00:45:39.276841Z"
}
}
}
```
* The `"uuid"` is the webhook UUID
* The `"data.uuid"` is the order UUID that can be used on the API call to get order details
* The `"data.capture.uuid"` is the UUID for the capture
```json theme={"system"}
{
"uuid": "6ee025c6-8acf-48fe-a6d6-b51693d64c60",
"created_at": "2025-04-12T00:20:07.44668Z",
"event": "order.captured",
"data_type": "order",
"data": {
"uuid": "b87305a1-6be3-4877-bcf0-2b5b7dfaeaf0",
"capture": {
"uuid": "b69b1ba8-e977-4f26-9253-06f14d941696",
"created_at": "2025-04-12T00:20:07.438365Z",
"amount": {
"amount_in_cents": 3000,
"currency": "USD"
}
}
}
}
```
* The `"data.uuid"` is the order UUID that can be used on the API call to get order details
Note on the `source` field:
* If the value is `"dashboard"`, it's initiated from the merchant dashboard
* If the value is `"gateway"`, it's via the gateway API
```json theme={"system"}
{
"uuid": "ed89f046-f55e-4fdd-9f65-ec3d8e961f99",
"created_at": "2025-04-12T00:24:39.809499Z",
"event": "order.refunded",
"data_type": "order",
"data": {
"uuid": "b69f882d-06c3-4f2e-b6e3-ce7a6c46e455",
"refund": {
"uuid": "479e9d25-d0a5-49df-a2d3-6ca1d75b8c57",
"created_at": "2025-04-12T00:24:39.805651Z",
"source": "dashboard",
"amount": {
"amount_in_cents": 500,
"currency": "USD"
}
}
}
}
```
The following applies to the following webhooks:
* `dispute.merchant_input_requested`
* `dispute.deadline_approaching`
* `dispute.closed.customer_win`
* `dispute.closed.merchant_win`
* `dispute.closed.neutral`
```json theme={"system"}
{
"uuid": "79f1e9cd-f1ef-42fa-b7b4-2ed8d9e9fae8",
"created_at": "2025-04-11T17:22:22.717757Z",
"event": "dispute.merchant_input_requested",
"data_type": "dispute",
"data": {
"customer_name": "John Doe",
"order_uuid": "e17280f3-d575-4bc2-99ff-ff881df7b137",
"order_reference_id": "order-reference-id-123",
"sezzle_order_id": "d2s7t-281qj-rf6ra-dqfcg",
"order_date": "2024-08-20",
"dispute_type": "No Product Or Service",
"dispute_due_date": "2025-04-08",
"dispute_id": 132,
"dispute_amount_in_cents": 2500,
"dispute_currency": "USD",
"dispute_status": "Closed All Win"
}
}
```
## Webhook Acceptance and Retries
* Considered delivered upon receiving any HTTP 2xx response, such as 200, 202, or 204.
* Any other response triggers retries:
* Multiple attempts in the first hour.
* A few attempts throughout the day.
* Final attempts one day and three days later, spanning five days total.
* If the final retry fails, the webhook subscription is deleted for all events.
* To resume receiving webhooks, recreate the webhook.
* Webhooks may not arrive in chronological order, as new ones can be sent before retries of older ones.
* Retried webhooks use the current merchant private key for signing, so the signature may differ from the original if the key has changed.