---
title: "Webhooks"
description: "Endpoints, every event and its payload, signatures, retries and resends."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

A store's webhook endpoints are sent the events they name as they happen: an order, a refund, a subscription renewing or failing to charge, access granted or taken away, a review, a certificate, a license issued, disabled, enabled or replaced by a new key, a device activated or deactivated on one, a request for approval or a waitlist place received, approved or declined, a new customer, an attendee registered on an event, or an event changed or canceled for those going. Each event is a signed `POST` to your URL.

## Endpoints

Create one with <a href="/merchant-api/reference/create-webhook/">`POST /webhooks`</a>, naming its URL and the events it takes:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/webhooks' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/sherpo/webhooks",
  "events": [
    "order.created",
    "order.refunded"
  ],
  "description": "Order sync"
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/webhooks', {
  body: {
    "url": "https://example.com/sherpo/webhooks",
    "events": [
      "order.created",
      "order.refunded"
    ],
    "description": "Order sync"
  },
});
```

Answers `201`, abridged:

```json
{
  "webhook": {
    "id": "c4b3a291-8f7e-4d6c-8b5a-49382716a5b4",
    "url": "https://example.com/sherpo/webhooks",
    "description": "Order sync",
    "events": [
      "order.created",
      "order.refunded"
    ],
    "enabled": true,
    "connection_ended_at": null,
    "created_at": "2026-11-03T10:00:00.000Z",
    "updated_at": "2026-11-03T10:00:00.000Z"
  },
  "secret": "whsec_3Jx9b2kQ7mVt4ZpR8nYc1LwE6aHs0DfG"
}
```

- The URL is `https` on a public host name: never an IP address, or a host resolving to a private, loopback or link-local address.
- Creating one needs `organization:write` plus the read scopes of its events' payloads, listed [below](#events), since what they send is read with your access.
- The answer holds the endpoint's signing secret, `whsec_...`. It is the only time any call answers it, so store it as a secret right away. A lost or leaked secret is rolled with <a href="/merchant-api/reference/roll-webhook-secret/">`POST /webhooks/{webhook}/secret/roll`</a>, which answers the new one; the old one signs nothing more. Rolling needs the scopes of the endpoint's events and of every event it still owes.
- <a href="/merchant-api/reference/update-webhook/">`PATCH /webhooks/{webhook}`</a> changes its URL, events, description or `enabled`; <a href="/merchant-api/reference/delete-webhook/">`DELETE /webhooks/{webhook}`</a> removes it. A disabled endpoint is sent nothing, and what it was owed fails.
- Endpoints created with a token are turned off when that token is revoked: `connection_ended_at` says when.

## A delivery

Each event is a `POST` with a JSON body and these headers:

| Header | Value |
| - | - |
| `Sherpo-Event-Id` | The event's `id`. |
| `Sherpo-Event-Type` | Its `type`. |
| `Sherpo-Signature` | `t=<unix seconds>,v1=<signature>`: see [signatures](#signatures). |

The body holds the event's `id`, its `type`, `created_at` (when the event was owed) and `data`:

```json
{
  "id": "8c7b6a59-4837-4261-9f8e-7d6c5b4a3928",
  "type": "order.created",
  "created_at": "2026-11-02T16:21:10.000Z",
  "data": {
    "order": {
      "id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
      "number": 1042,
      "customer": {
        "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": null,
        "erased": false
      },
      "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "currency": "eur",
      "exponent": 2,
      "amount": 4900,
      "discount": 0,
      "total": 4900,
      "settled": 4900,
      "refunded": 0,
      "refund_status": "none",
      "free": false,
      "source": "checkout",
      "source_key": null,
      "note": null,
      "occurred_at": "2026-11-02T16:21:09.000Z",
      "recorded_at": "2026-11-02T16:21:10.000Z"
    }
  }
}
```

The objects in `data` read exactly as the API answers the same rows, as they stood at the first attempt, so one parser reads both: here `order` is what <a href="/merchant-api/reference/get-order/">`GET /orders/{order}`</a> answers, but for its `refunds_refused`, which the API answers and a webhook's body leaves out. Amounts are minor units with the `exponent` that scales them. Each event's `data` is below.

## Events

| Event | Scopes its payload needs | `data` |
| --- | --- | --- |
| `products.unlocked` (Access granted) | `customer:read` `transaction:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `order_id`: the order that granted them, null once gone; `grant_ids`; `products`: the products unlocked, each as the API summarizes it (`id`, `slug`, `title`, `category`, `deleted`), leaving out any that is gone. |
| `request.received` (Request received) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request`: the request as `GET /products/{product}/requests` lists it, `status` `pending`; `product`: its product, summarized as in `products`, null once gone. Sent when a buyer's order of a product that requires approval waits for you, its seats held; a paid one's `payment` is `saved`, its card charged once you approve. |
| `request.waitlisted` (Added to the waitlist) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request` and `product` as in `request.received`, `status` `waitlisted`. Sent when a buyer joins a full event's waitlist. |
| `request.approved` (Request approved) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request` and `product` as in `request.received`, `status` `approved` with its `grant_id`. Sent when you approve a request or promote a waitlisted buyer, who holds the product from then on. |
| `request.declined` (Request declined) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request` and `product` as in `request.received`, `status` `declined`. Sent when you decline a request or a waitlist place, its seats given back. |
| `request.expired` (Request released) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request` and `product` as in `request.received`, `status` `declined`, `closed_reason` `expired`. Sent when the card hold of a paid request was released a day before it lapsed, as nobody decided it in time; its seats are given back and nothing is charged. |
| `request.payment_due` (Request payment due) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `request` and `product` as in `request.received`, `status` `pending`, `payment` `due`. Sent when the charge of a paid request you approved or promoted failed or found no saved card, so the buyer is asked to pay it themselves. |
| `discounts.unlocked` (Discount unlocked) | `customer:read` `discount:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `discount`: the discount as `GET /discounts/{discount}` answers it, without its `scopes`, `affiliates`, `customers` and `usage`; `products`: the products it applies to, each as the API summarizes it (`id`, `slug`, `title`, `category`, `deleted`), leaving out any that is gone. |
| `refund.processed` (Refund processed) | `customer:read` `transaction:read` `product:read` `revenue:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `refund`: the refund as an order's `refunds` list it; `products`: the order's products, each as the API summarizes it (`id`, `slug`, `title`, `category`, `deleted`), leaving out any that is gone. |
| `affiliate.earned` (Affiliate commission earned) | `transaction:read` `affiliate:read` `revenue:read` | `order_id`; `affiliate`: `{ user_id }`; `commissions`: what the order earned them, each as an order's `affiliates` list it, plus the line's `product_id`. |
| `subscription.created` (Subscription started) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone. |
| `subscription.renewed` (Subscription renewed) | `customer:read` `subscription:read` `product:read` `revenue:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `period_id`: the period it renewed into; `charged`: a money object (`amount` in minor units, `currency`, `exponent`). |
| `subscription.reminder` (Renewal reminder) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `ends_at`: when the paid run ends; `renews`: whether it renews then; `charge`: what the renewal will charge, on the plan `scheduled_change` names when there is one, as a money object (`amount` in minor units, `currency`, `exponent`). |
| `subscription.plan_changed` (Plan changed) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `previous` and `current`: what the old and the new plan charge, each a money object (`amount` in minor units, `currency`, `exponent`). |
| `subscription.payment_failed` (Payment failed) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `attempt` and `of`: which charge attempt failed, out of how many; `ends_at`: when the paid run ends. |
| `subscription.past_due` (Payment past due) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `transition_id`. |
| `subscription.unpaid` (Subscription unpaid) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone. |
| `subscription.canceled` (Subscription canceled) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone; `effective_at`: when access ends. |
| `subscription.reactivated` (Subscription reactivated) | `customer:read` `subscription:read` `product:read` | `customer`; `subscription`: the subscription as `GET /subscriptions/{subscription}` answers it, without its `customer`, `product` and `periods`, plus `paid_through` (the end of its paid run); `product`: its product, summarized as in `products`, null once gone. |
| `event.registered` (Event registration) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `attendee`: the attendee as `GET /products/{product}/attendees` lists them; `product`: the event, summarized as in `products`, null once gone; `sessions`: its sessions not yet ended, each as `GET /products/{product}/sessions` lists them. Sent once a customer is listed going on an event: a purchase, a grant, or a return after their access lapsed, never a renewal or a change of ticket. |
| `event.updated` (Event changed) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `attendee`, `product` and `sessions` as in `event.registered`; `removed_sessions`: the sessions taken off the schedule, each its `id`, `starts_at`, `ends_at`, `time_zone`, `venue` and `online_label`. Sent to each attendee going a few minutes after the edits stop, when a session ahead is added, moved, has its place changed or is taken off, or the event's location changes; once a canceled event has a session ahead again, `removed_sessions` also names the sessions its cancellation took off. |
| `event.canceled` (Event canceled) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `attendee`, `product` and `sessions` (none) as in `event.registered`; `removed_sessions` as in `event.updated`. Sent to each attendee going once the event's last session ahead is taken off the schedule, unless a session ahead is added before it goes. `removed_sessions` also repeats the sessions an earlier `event.canceled` named when a session added since is taken off again: match them by `id`. |
| `event.purchase_canceled` (Event canceled for a buyer) | `customer:read` `transaction:read` `product:read` `revenue:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none, the buyer; `product`: the event, summarized as in `products`, null once gone; `removed_sessions` as in `event.updated`; `guests`: each guest the buyer named who held a ticket when the event was canceled, as their `customer_id`, the `name` and `email` the buyer gave (null once erased) and their ticket's `status` (`active` or `refunded`); `refunds`: the buyer's refunds for the event, each as `GET /products/{product}/event_refunds` lists it, as they stood at the first attempt (usually `pending` for a Stripe payment). Sent once per buyer and event when the store cancels an event and the buyer holds none of the tickets they bought, having named a guest for each; a buyer holding a ticket hears `event.canceled` instead. |
| `event.refund_failed` (Event refund failed) | `customer:read` `transaction:read` `product:read` `revenue:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none, the buyer; `product`: the event, summarized as in `products`, null once gone; `refund`: the failed refund as `GET /products/{product}/event_refunds` lists it, as it stood at the first attempt; `retries`: how many times it had been retried when this failure landed, 0 for its first try (a retry since may already show it `pending` or `refunded`); `amount`: what the failed try was to give back, in the refund's currency and `exponent`, which is less than the refund's own `amount` when part of the payment went back another way, or null when the refund failed before Stripe was asked. Sent each time a canceled event's refund turns `failed`, whether Stripe refused it, failed it later or could not be reached, and again for each retry that fails. The buyer is emailed once per refund, for a failure after their cancellation email said the refund was on its way. |
| `access.revoked` (Access revoked for cause) | `customer:read` `transaction:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `revocation`: the revocation as `GET /revocations` lists it, its refund's amount withheld; `products`: the products whose access ended, summarized as in `products`. Sent when a seller revokes a customer's access for cause, with the mail that always tells the customer. |
| `order.created` (Order created) | `customer:read` `transaction:read` `product:read` `revenue:read` | `order`: the order as `GET /orders/{order}` answers it, its `customer` and takings included. |
| `order.refunded` (Order refunded) | `customer:read` `transaction:read` `product:read` `revenue:read` | `order`: the order as `GET /orders/{order}` answers it; `refund`: the refund as an order's `refunds` list it; `refunded`: what the refund had given back when the event happened, as a money object (`amount` in minor units, `currency`, `exponent`); `dispute`: whether a lost dispute took it. Sent for every refund, a dispute's too (which `refund.processed` leaves out), and again when a processor's refund grows. |
| `review.created` (Review posted) | `customer:read` `review:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `review`: the review as `GET /reviews` lists it, without its `customer` and `product`; `product`: its product, summarized as in `products`, null once gone. Sent when a customer reviews a product, never for an edit. |
| `grant.revoked` (Access revoked) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `grant`: the grant as `GET /grants` lists it, without its `customer` and `product`, its `ends_at` and `end_reason` set; `cause`: `merchant`, `refund`, `account_erased`, `guest_changed` (a seller revoked it or ended its subscription at once, a refund took it, or the customer erased their account); `product`: its product, summarized as in `products`, null once gone. Sent when access is taken away, never when a grant runs out or an upgrade's new grant replaces it. |
| `certificate.issued` (Certificate issued) | `customer:read` `certificate:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `issue`: the award's own fields, its `product_id` included, as a certificate's issues list them; `certificate`: the certificate's own fields, as `GET /products/{product}/certificates` lists them; `product`: its product, summarized as in `products`, null once gone. |
| `license.issued` (License issued) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license`: the license's own fields, never its key: its `id`, `product_id`, `customer_id`, `source` (`issued` or `imported`), `status` (`active`, `expired`, `revoked`, `disabled` or `replaced`, read from the customer's access), `expires_at` (when that access ends, null while it never does), `reason` (why it isn't active: `replaced`, `disabled`, `lapse`, `refund` or `revoke`; null while active), `has_access` (whether the customer has that access now, whatever the status), `activation_limit`, `uses`, `metadata`, `created_at`, `disabled_at`, `disabled_reason`, `replaced_by` and `last_verified_at`; `product`: its product, summarized as in `products`, null once gone. Sent once per customer and software product, when their first access to it lands, never for a renewal or a plan change, which keep the license. |
| `license.disabled` (License disabled) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license` and `product` as in `license.issued`, the license as it reads when the event is sent; `disabled_at` and `reason`: when the merchant disabled it and why (null for no reason), as they were then, even if it was enabled again since. A disabled license checks as invalid whatever the customer's access, which its `has_access` tells. |
| `license.enabled` (License enabled) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license` and `product` as in `license.issued`; `enabled_at`: when the merchant enabled it again, after which it checks as the customer's access says. |
| `license.replaced` (License replaced) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license`: the new license, as in `license.issued`, never its key; `replaced_id`: the license it replaced, whose key stopped checking at once; `product` as in `license.issued`. Sent whenever a key is rotated, by the merchant or by the customer. |
| `license.activated` (License activated) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license` and `product` as in `license.issued`; `activation`: the device, never its instance id: its `id`, `license_id`, `name`, `status` (`active`, `inactive` or `deactivated`), `created_at`, `activated_at`, `last_seen_at`, `deactivated_at` and `deactivated_by`; `activated_at`: when this activation counted it. Sent when a license counts a new device, or one freed or gone inactive comes back, never for a refresh of a device it already counts. |
| `license.deactivated` (License deactivated) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license`, `product` and `activation` as in `license.activated`; `deactivated_at` and `deactivated_by` (`customer`, `merchant` or `software`): when and by whom this deactivation freed it. Replacing a key frees the old key's devices without this event, as `license.replaced` tells it. |
| `license.limit_reached` (License activation limit reached) | `customer:read` `product:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none; `license` and `product` as in `license.issued`; `reached_at`: when a device was refused; `count`: the devices the license counted then; `limit`: the most it held then, 10,000 when nothing else limits it. Sent at most once an hour per license, however many devices are refused. |
| `customer.created` (Customer created) | `customer:read` | `customer`: the customer as the API summarizes them (`id`, `name`, `email`, `phone`, `erased`), null for none. Sent when someone first signs in to the store, never for a customer a grant by email only invited. |

A subscription's events carry the subscription and its product beside the customer:

```json
{
  "id": "2a1b0c9d-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
  "type": "subscription.renewed",
  "created_at": "2026-12-02T16:21:12.000Z",
  "data": {
    "customer": {
      "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": null,
      "erased": false
    },
    "subscription": {
      "id": "5d4c3b2a-1908-4f7e-9d6c-5b4a39281706",
      "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "status": "active",
      "cancel_at_period_end": false,
      "display_status": "active",
      "next_event": {
        "kind": "renews",
        "at": "2027-01-02T16:21:09.000Z"
      },
      "actions": {
        "cancel": {
          "period_end": true,
          "now": true
        },
        "resume": false
      },
      "period_end": "2027-01-02T16:21:09.000Z",
      "created_at": "2026-11-02T16:21:09.000Z",
      "ended_at": null,
      "paid_through": "2027-01-02T16:21:09.000Z"
    },
    "product": {
      "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "slug": "watercolor-basics",
      "path": "/p/watercolor-basics",
      "url": "https://shop.example.com/p/watercolor-basics",
      "title": "Watercolor basics",
      "category": "course",
      "deleted": false
    },
    "period_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
    "charged": {
      "amount": 900,
      "currency": "eur",
      "exponent": 2
    }
  }
}
```

And granting access carries every product it unlocked:

```json
{
  "id": "6b5a4938-2716-4f5e-8d4c-3b2a19087f6e",
  "type": "products.unlocked",
  "created_at": "2026-11-02T16:21:10.000Z",
  "data": {
    "customer": {
      "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": null,
      "erased": false
    },
    "order_id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
    "grant_ids": [
      "4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807"
    ],
    "products": [
      {
        "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
        "slug": "watercolor-basics",
        "path": "/p/watercolor-basics",
        "url": "https://shop.example.com/p/watercolor-basics",
        "title": "Watercolor basics",
        "category": "course",
        "deleted": false
      }
    ]
  }
}
```

New events and new fields in `data` may appear within `/v1` (see [versioning](/merchant-api/versioning)): ignore what you don't know.

## Signatures

`Sherpo-Signature` is `t=<unix seconds>,v1=<signature>`, where the signature is the hex HMAC-SHA256 of `t`, a dot and the raw body, keyed with the endpoint's whole secret as it was answered (`whsec_...` included).

- Verify it against the raw body, before parsing it: a body parsed and serialized again may differ by a byte.
- Compare in constant time.
- Refuse a `t` more than a few minutes from your clock, so a captured delivery can't be replayed later.

In JavaScript (browsers, Node 20 and later, Workers, Deno and Bun), as the API's own tests run it:

```js
// rawBody is the request body exactly as received, before any JSON parsing.
async function verifyWebhook(secret, rawBody, signatureHeader, toleranceSeconds = 300) {
  if (!secret) throw new Error('The webhook secret is missing.');
  const fields = Object.fromEntries(
    (typeof signatureHeader === 'string' ? signatureHeader : '').split(',').map((field) => field.split('=', 2)),
  );
  const t = Number(fields.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(fields.v1 ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify'],
  );
  const signature = new Uint8Array(
    fields.v1.match(/../g).map((byte) => parseInt(byte, 16)),
  );
  // verify compares in constant time.
  return crypto.subtle.verify('HMAC', key, signature, encoder.encode(t + '.' + rawBody));
}
```

The same in Python:

```python
import hashlib, hmac, re, time
from typing import Optional

def verify_webhook(secret: str, raw_body: bytes, signature_header: Optional[str], tolerance_seconds: int = 300) -> bool:
    if not secret:
        raise ValueError("The webhook secret is missing.")
    fields = dict(field.split("=", 1) for field in (signature_header or "").split(",") if "=" in field)
    t, v1 = fields.get("t", ""), fields.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(time.time() - int(t)) > tolerance_seconds:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())
```

## Answers and retries

Answer any `2xx` within 5 seconds; the answer's body is never read. Do the work after answering, or quickly.

- A redirect (`3xx`) is not followed and fails the delivery at once, as does a host that resolves to a private, loopback or link-local address.
- Any other status, a timeout or a failed connection is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: 8 attempts over about 45 hours, after which the delivery fails.
- While your host can't be resolved because the resolver itself fails, attempts wait for up to a day without counting.

The body is fixed at the first attempt: every retry sends the same bytes, signed anew, unless the customer it names is erased meanwhile, or was invited by email and has since signed in, when the next attempt builds it again for who they are now.

## Repeats and order

Deliveries may repeat, and may arrive in any order: a refund's event can come before its order's. Timestamps can't order them either: `created_at` is to the second, and an event's `data` is the row as it stood when its delivery was first built. To keep a copy of a row, treat an event as word that the row changed, read the row from the API, and write what it answers, one read and write of a row at a time, so the newest read writes last. Some changes send no event (a refund a payment processor fails is taken back, lowering an order's `refunded`), so read your copies back now and then too. The [receive webhooks guide](/merchant-api/guides/receive-webhooks) does both.

## Deliveries and resends

<a href="/merchant-api/reference/list-webhook-deliveries/">`GET /webhook_deliveries`</a> lists an endpoint's last deliveries, within its `filter[webhook_id]`, with their attempts, the last status your endpoint answered and the last error:

```bash
curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/webhook_deliveries?filter[webhook_id]=c4b3a291-8f7e-4d6c-8b5a-49382716a5b4&filter[status]=failed' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/webhook_deliveries', {
  query: [
    ['filter[webhook_id]', 'c4b3a291-8f7e-4d6c-8b5a-49382716a5b4'],
    ['filter[status]', 'failed'],
  ],
});
```

<a href="/merchant-api/reference/resend-webhook-delivery/">`POST /webhook_deliveries/{delivery}/resend`</a> sends a delivery again, with the same event `id` and body. One with no body kept (nothing was sent, or its customer was erased) is built anew, with the resend's `created_at`. Resending needs `organization:write` and the event's read scopes.

An event undone since (a refund taken back, a certificate revoked or taken back by an undone check-in, a license dropped because the customer an invite became already held one) is never sent again: its retries send nothing, its deliveries read `undone: true`, and its resends are refused.

Source: https://docs.sherpo.io/merchant-api/webhooks/index.mdx
