Webhooks
A store's webhook endpoints (POST /v1/stores/{store}/webhooks) are sent the events they name as they happen. An endpoint is an https URL 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 its events' payloads carry, listed below, and answers its signing secret, the only time any call answers it: keep it, and roll it (POST /v1/stores/{store}/webhooks/{webhook}/secret/roll, which needs the scopes of its events and of every event it still owes) if it is lost or leaked; the old secret signs nothing more.
A delivery
Each event is a POST with a JSON body:
{
"id": "<event id>",
"type": "subscription.renewed",
"created_at": "<ISO 8601 time the event was owed>",
"data": { ... }
}
with the headers Sherpo-Event-Id (the event's id), Sherpo-Event-Type (its type) and Sherpo-Signature (see signatures). Objects in data read exactly as the API answered the same rows at the first attempt, so one parser reads both; amounts are minor units with the exponent that scales them.
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. |
request.receivedRequest 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.waitlistedAdded 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.approvedRequest 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.declinedRequest 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.expiredRequest 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_dueRequest 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.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. |
event.registeredEvent 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.updatedEvent 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.canceledEvent 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_canceledEvent 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_failedEvent 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.revokedAccess 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.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, 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.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, 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.issuedLicense 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.disabledLicense 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.enabledLicense 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.replacedLicense 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.activatedLicense 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.deactivatedLicense 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_reachedLicense 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.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. |
Nothing is sent for a subscription billed outside Sherpo, such as by a payment processor.
Answers and retries
Answer any 2xx within 5 seconds; the answer's body is never read. 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 connection that fails is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours: 8 attempts over about 45 hours, after which the delivery fails. While the endpoint's host cannot be resolved because the resolver itself fails, attempts wait for up to a day without counting. A disabled endpoint is sent nothing, and what it was owed fails.
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 a customer a grant by email invited who has since signed in, when the next attempt builds it again for who they are now. Resending a delivery (POST /v1/stores/{store}/webhook_deliveries/{delivery}/resend) sends the same event id and body again; one with no body kept (nothing was sent, or its customer was erased) is built anew, with the resend's created_at. An event undone since (a refund taken back, a certificate revoked, 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. Deliveries may repeat and arrive in any order: act on each id once, and read the current state from the API when the order matters. GET /v1/stores/{store}/webhook_deliveries lists an endpoint's last deliveries with their attempts and errors.
Signatures
Sherpo-Signature: 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 secret as it was answered (the whole whsec_... string). Verify it against the raw body before parsing it, compare in constant time, and refuse a t more than a few minutes from your clock, so a captured delivery cannot be replayed later. In JavaScript (browsers, Node 20 and later, Workers, Deno and Bun):
// 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));
}
And a Worker receiving deliveries with it:
export default {
async fetch(request, env) {
const body = await request.text();
const signature = request.headers.get('Sherpo-Signature') ?? '';
if (!(await verifyWebhook(env.SHERPO_WEBHOOK_SECRET, body, signature)))
return new Response('Bad signature', { status: 400 });
const event = JSON.parse(body);
// A delivery may come more than once, even at once: record its id in the same
// transaction as what it changes (webhook_events has id as its primary key),
// so a repeat changes nothing and a failure leaves it to the retry.
// statementsFor answers the D1 statements the event makes; work outside D1 cannot join them.
try {
await env.DB.batch([
env.DB.prepare('INSERT INTO webhook_events (id) VALUES (?)').bind(event.id),
...statementsFor(event),
]);
} catch (error) {
if (!String(error).includes('UNIQUE constraint failed: webhook_events.id')) throw error;
}
return new Response(null, { status: 204 });
},
};