A store’s webhook endpoints are sent the events they name as they happen. An agent can set them up through the merchant MCP server. What an endpoint receives is the same as with the merchant API.
Scopes
The webhook tools need the business’s organization scopes, which only the Everything set holds (see Scopes):
organization:read:list_webhooks,get_webhook,list_webhook_deliveries.organization:write:create_webhook,update_webhook,roll_webhook_secret,resend_webhook_delivery.organization:delete:delete_webhook.
An endpoint also needs the read scopes its events’ payloads carry, listed in the events table. Without one, the call answers HTTP 403 with insufficient_scope. Only the events that carry amounts taken or paid out need revenue:read. The table shows each event’s scopes.
Creating an endpoint
create_webhook takes:
url: anhttpsURL on a public host name, up to 2,048 characters, with no credentials and no fragment. An IP address,localhost, a name without a dot, or a name ending in.localhost,.local,.internalor.home.arpais refused.events: the events to send, at least one, each once.description: optional, from 1 to 500 characters, or null.enabled: optional, true by default.
{
"url": "https://hooks.example.com/sherpo",
"events": ["order.created", "refund.processed"],
"description": "Orders to the warehouse"
}It answers the endpoint as webhook and its signing secret as secret, a string starting with whsec_. This is the only time a call answers the secret: keep it. If the answer is lost, roll the secret.
{
"webhook": {
"id": "8e4b1d27-6c3a-4f90-b2e5-0a7d9c1f3e68",
"url": "https://hooks.example.com/sherpo",
"description": "Orders to the warehouse",
"events": ["order.created", "refund.processed"],
"enabled": true,
"connection_ended_at": null,
"created_at": "2026-11-03T14:02:11.000Z",
"updated_at": "2026-11-03T14:02:11.000Z"
},
"secret": "whsec_Qm3vT8kZp1rXw7Lc2nYb5dHs0aGf4eJu"
}A store holds at most 20 endpoints. Past that, create_webhook is a conflict.
Changing an endpoint
update_webhookchanges theurl,events,descriptionorenabled. A new URL or added events need the read scopes of the events. Turning an endpoint off withenabled: falsesends it nothing new, and each delivery it was still owed fails when next tried while the endpoint is still off, with “The endpoint is disabled.” Turned back on before then, the endpoint is sent them.roll_webhook_secretanswers a new secret, once. The old one stops signing at once, with no overlap, so update your receiver as soon as you roll. It needs the read scopes of the endpoint’s events and of every event it still owes.delete_webhookdeletes the endpoint and its history. What it was still owed is never sent.
Endpoints and connections
An endpoint belongs to the connection that set it up. Moving it to a new URL makes the calling connection its owner. Rolling its secret ties it to the calling connection as well, since that connection now holds the secret.
When either connection is revoked, expires, is removed from the business or loses the access its events need, the endpoint is turned off: enabled reads false and connection_ended_at says when. What it still owed fails with “Not sent: the connection that set up the endpoint ended.” Revoking a connection made before connections could reach several businesses, on the API tokens page, says so before you confirm.
To turn it back on, call update_webhook with enabled: true. The calling connection becomes its owner, and it needs the read scopes of the endpoint’s events. It is sent the events that happen from then on. What failed while it was off is not sent again unless you resend it. When the ended connection held the endpoint’s secret, Sherpo replaced it: roll the secret to get one you can verify with.
An endpoint is never turned off for failing deliveries.
Events
| Event | When | Scopes it 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 delivery
Each event is a POST of a JSON body with Content-Type: application/json and User-Agent: Sherpo-Webhooks/1:
{
"id": "2d7f9a14-3b8e-4c61-a5d0-9e2c7b4f1a83",
"type": "order.created",
"created_at": "2026-11-03T14:20:37.000Z",
"data": { "order": { "id": "5f0c8d2e-41a7-4b9e-9c3d-2a6f1e8b7c40" } }
}data is shown short here. Its records read as the merchant API answers them, and the matching tools answer them the same way, so the API paths in the table above name what each event holds.
The body is fixed at the first attempt, so a retry sends the same event, with two exceptions:
- Erasing a customer clears the bodies of their deliveries. A later attempt or a resend builds the body again, without their details.
- When a customer accepts an invitation, the invitation’s pending deliveries are built again to name that customer.
Nothing is sent for a subscription billed outside Sherpo, such as by a payment processor. An event undone after it happened, such as a refund taken back, is not sent from then on, its retries included.
Deliveries may repeat and arrive in any order: act on each id once, and read the current state through the tools when the order matters.
Sherpo adds three headers:
Sherpo-Signature: the signature, below.Sherpo-Event-Id: the event'sid, the same on every attempt.Sherpo-Event-Type: the event'stype.
Verifying the signature
Sherpo-Signature reads t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of "<t>.<raw body>", keyed with the whole secret as it was answered, whsec_ included. Each attempt is signed again.
Verify it against the raw body, before parsing it, and 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:
// 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));
}Answers and retries
Answer any 2xx to accept a delivery; the answer’s body is never read. A redirect is never followed: it fails the delivery for good, with no retry. So does a host that resolves to an address webhooks never reach, such as a private, loopback or link-local one. While the endpoint’s host can’t be resolved because the resolver itself fails, attempts wait for up to a day without counting. Other failures are retried:
An attempt that can't reach the endpoint, gets no answer within 5 seconds, or answers a status that is neither 2xx nor a redirect is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours: 8 attempts in all.
Deliveries
list_webhook_deliveries lists an endpoint’s deliveries, newest first, with their attempts, last answer and last error. Its query.filter needs webhook_id, and also takes status (pending, succeeded or failed) and event. An endpoint keeps its last 100 settled deliveries.
{ "query": { "filter": { "webhook_id": "8e4b1d27-6c3a-4f90-b2e5-0a7d9c1f3e68", "status": "failed" } } }resend_webhook_delivery sends a delivery’s event to its endpoint again, with the same event id, so a receiver that records ids skips one it already handled. It needs the read scopes its payload carries, and is a conflict:
- with
{ "field": "status", "current": "pending" }while the delivery is still being tried; - with
{ "field": "status", "current": "disabled" }while the endpoint is turned off; - with
{ "field": "delivery", "current": "undone" }for an event undone since, such as a refund taken back, which is never sent again.