Skip to content

Webhooks

Set up a store's webhook endpoints over MCP, and receive and verify what Sherpo sends them.

Updated

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):

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: an https URL 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, .internal or .home.arpa is 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_webhook changes the url, events, description or enabled. A new URL or added events need the read scopes of the events. Turning an endpoint off with enabled: false sends 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_secret answers 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_webhook deletes 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's id, the same on every attempt.
  • Sherpo-Event-Type: the event's type.

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.

Type to search…

↑↓ navigate↵ selectEsc close