Webhooks

Orchard POSTs a signed JSON event to your endpoint when something happens in your store — an order is paid, a subscription changes, a refund is issued. Use them to react in your own systems (fulfillment, CRM, analytics) without polling.

These are Orchard’s outbound events to your systems. They are separate from the Stripe webhooks Orchard receives at /api/webhooks/stripe/{tenant_slug} (those carry Stripe’s own signature and are internal to Orchard).

Subscribe

Create an endpoint in the admin at Settings → Webhooks (admin.theorchard.dev/t/{slug}/settings/webhooks):

1. Enter your HTTPS URL and select the event types to receive.
2. Orchard shows a signing secret once — copy it now. It is never displayed again (you can regenerate it later, which invalidates the old one).
3. Use the Test button to send a webhook.ping immediately and confirm your endpoint is reachable.

The admin also shows a delivery log (status, response code, attempts) for every endpoint.

How delivery works

• Lifecycle events (order.*, subscription.*) are queued the moment the state changes, then delivered by a background worker. First delivery normally lands within ~5 minutes — they are intentionally off the checkout path so a slow endpoint never delays a customer’s payment.
• The Test ping is sent immediately (synchronously) when you click Test.
• Your endpoint should respond with any 2xx status to acknowledge. Anything else (or a timeout — the request budget is 15 seconds) is treated as a failure and retried.

Retries

After a failed attempt, Orchard retries with backoff:

Up to 5 attempts total. Disabling an endpoint halts its pending retries.

Idempotency

Every delivery carries a stable X-Orchard-Delivery id (a UUID). Retries of the same delivery reuse the same id. Dedupe on it — store processed ids and ignore repeats so a retry can’t double-apply an effect on your side.

Next

• Events & payloads — the event catalog, the envelope shape, headers, and what’s in data for each event.
• Verifying signatures — confirm a delivery really came from Orchard, with a copy-paste example.