Skip to content

Webhooks

Endpoints, every event and its payload, signatures, retries and resends.

Updated

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 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, 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 POST /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 or enabled; 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_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.

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

EventScopes its payload needsdata
products.unlocked
Access granted
customer:read transaction:read product:readcustomer: 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.unlocked
Discount unlocked
customer:read discount:read product:readcustomer: 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:readcustomer: 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:readorder_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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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:readcustomer; 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.created
Order created
customer:read transaction:read product:read revenue:readorder: the order as GET /orders/{order} answers it, its customer and takings included.
order.refunded
Order refunded
customer:read transaction:read product:read revenue:readorder: 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:readcustomer: 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:readcustomer: 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.issued
Certificate issued
customer:read certificate:read product:readcustomer: 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.created
Customer created
customer:readcustomer: 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 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:

// 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.

Type to search…

↑↓ navigate↵ selectEsc close