Webhooks
Wilby tells your server about every step, signed so you know it came from us.
curl -X POST https://app.usewilby.com/v1/webhook-endpoints \
-H "Authorization: Bearer $OH_KEY" \
-H "Idempotency-Key: hook-1" \
-H "content-type: application/json" \
-d '{
"url": "https://example.com/hooks/oh",
"events": [
"order.*",
"incremental_charge.*"
]
}'
The answer includes the signing secret, once. Each delivery has a header:
Wilby-Signature: t=1731200000,v1=5f2b…
Also sent: Wilby-Event-Id (one per event, for handling each event once) and Wilby-Delivery-Id. During the move from the earlier name, the same values are also sent as Openhold-Signature, Openhold-Event-Id and Openhold-Delivery-Id; check either.
Compute HMAC-SHA256 with your secret over t + "." + raw body and compare with v1 (the same scheme as Stripe). During a secret rotation, two v1 values are sent for 24 hours. Failed deliveries are retried for about 3 days; see them with GET /v1/webhook-deliveries. POST /v1/webhook-endpoints/{id}/test sends a signed test ping.
Events
Subscribe to one (order.captured), a group (order.*) or all (*). The list is also at GET /v1/event-types. Every event has id, type, created_at, order_id when it is about an order, order and summary (the order and its screen-ready block, see Objects), data (what happened) and record (the signed record entry, exactly as signed).
| Event | When |
|---|---|
order.created | An order was created (including orders an AI agent placed through your storefront). |
order.confirmed | The store confirmed the order. |
order.authorized | The order's money was authorized (held) or charged. |
order.authorization_failed | Authorizing the order's money failed. |
order.captured | The final amount was captured. |
order.cancelled | The order was cancelled. |
order.expired | The order expired before it was paid; any hold was released. |
payment.authorized | A payment was authorized (held). |
payment.captured | A held payment was captured. |
payment.charged | A payment was charged at once. |
payment.voided | A hold was released. |
payment.refunded | A payment was refunded. |
payment.authorize_failed | Authorizing a payment failed. |
payment.charge_failed | A charge failed. |
payment.capture_failed | A capture failed. |
payment.void_failed | Releasing a hold failed. |
payment.refund_failed | A refund failed. |
payment.reported | You reported a payment and it matched an approval. |
payment.reported_unapproved | You reported a payment Wilby didn't approve. |
payment.cleared | A bank debit cleared. |
payment.returned | A bank debit came back (returned by the bank). |
refund.waiting_for_bank | A refund is waiting for a bank debit to clear first. |
charge.approval | Wilby decided on a charge (approved or not). |
incremental_charge.requested | You asked the customer to approve an incremental charge. |
incremental_charge.approved | The customer (or their rule) approved an incremental charge. Approved means yes, not that money moved. |
incremental_charge.declined | The customer declined an incremental charge. |
incremental_charge.expired | The customer didn't answer in time. |
incremental_charge.charge_failed | Charging an approved incremental charge failed. |
incremental_charge.cancelled | The store withdrew an incremental charge. |
authorization.captured_early | A hold was captured early because it was about to expire. |
authorization.reauthorized | A hold was renewed. |
authorization.expired | A hold expired at the processor. |
authorization.expiring_soon | A hold will expire soon. |
tip.added | The customer added a tip. |
evidence.added | Evidence was added to an order. |
refund.goodwill | A goodwill refund was recorded. |
dispute.opened | A dispute was opened. |
dispute.sent_to_review | A dispute was sent for review. |
dispute.resolved | A dispute was settled. |
dispute.chargeback_received | The processor reported a chargeback. |
customer.code_requested | A customer asked for a one-time code: text it to them (when you text codes). |
credential.issued | Wilby issued a signed credential (permission) for a customer. |