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

Options
Template

string

Unique identifier for the webhook event.

string

Timestamp (ISO 8601) when the event was generated.

string

Type of the eventAvailable 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

string

Type of data associated with the event.Available options: customer, order, dispute

object

Payload data specific to the event type. See options in the applicable accordion below.

{
    "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

customer.tokenized

{
    "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"
        }
    }
}

order.authorized

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

{
    "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"
        }
    }
}

order.captured

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

{
    "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"
            }
        }
    }
}

order.refunded

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

{
    "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"
            }
        }
    }
}

dispute

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

{
    "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.

API Reference

Tokenization

v1 (deprecated)

Webhook Signature, Acceptance and Retries