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 new customer. Each event is a signed POST to your URL.
Endpoints
Create one with POST /webhooks, naming its URL and the events it takes:
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"
}'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:
{
"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
httpson a public host name: never an IP address, or a host resolving to a private, loopback or link-local address. - Creating one needs
organization:writeplus the read scopes of its events’ payloads, listed below, 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 withPOST /webhooks/{webhook}/secret/roll, 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. PATCH /webhooks/{webhook}changes its URL, events, description orenabled;DELETE /webhooks/{webhook}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_atsays 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. |
The body holds the event’s id, its type, created_at (when the event was owed) and data:
{
"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 GET /orders/{order} answers. Amounts are minor units with the exponent that scales them. Each event’s data is below.
Events
| Event | Scopes its payload needs | data |
|---|---|---|
products.unlockedAccess 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. |
discounts.unlockedDiscount 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.processedRefund 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.earnedAffiliate 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.createdSubscription 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.renewedSubscription 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.reminderRenewal 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_changedPlan 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_failedPayment 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_duePayment 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.unpaidSubscription 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.canceledSubscription 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.reactivatedSubscription 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. |
order.createdOrder created | customer:read transaction:read product:read revenue:read | order: the order as GET /orders/{order} answers it, its customer and takings included. |
order.refundedOrder 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.createdReview 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.revokedAccess 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 (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.issuedCertificate 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, as a certificate's issues list them; certificate: the certificate's own fields, as GET /certificates lists them; product: its product, summarized as in products, null once gone. |
customer.createdCustomer 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:
{
"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:
{
"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): 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
tmore 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:
// 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:
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 does both.
Deliveries and resends
GET /webhook_deliveries lists an endpoint’s last deliveries, within its filter[webhook_id], with their attempts, the last status your endpoint answered and the last error:
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"const answer = await sherpo('GET', '/v1/stores/STORE_ID/webhook_deliveries', {
query: [
['filter[webhook_id]', 'c4b3a291-8f7e-4d6c-8b5a-49382716a5b4'],
['filter[status]', 'failed'],
],
});POST /webhook_deliveries/{delivery}/resend 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) is never sent again: its retries send nothing, its deliveries read undone: true, and its resends are refused.