Wilby DocsGet Sandbox Keys

Webhooks

Wilby tells your server about every step, signed so you know it came from us.

curl -X POST https://dev.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).

EventWhen
order.createdAn order was created (including orders an AI agent placed through your storefront).
order.confirmedThe store confirmed the order.
order.authorizedThe order's money was authorized (held) or charged.
order.authorization_failedAuthorizing the order's money failed.
order.capturedThe final amount was captured.
order.cancelledThe order was cancelled.
order.expiredThe order expired before it was paid; any hold was released.
payment.authorizedA payment was authorized (held).
payment.capturedA held payment was captured.
payment.chargedA payment was charged at once.
payment.voidedA hold was released.
payment.refundedA payment was refunded.
payment.authorize_failedAuthorizing a payment failed.
payment.charge_failedA charge failed.
payment.capture_failedA capture failed.
payment.void_failedReleasing a hold failed.
payment.refund_failedA refund failed.
payment.reportedYou reported a payment and it matched an approval.
payment.reported_unapprovedYou reported a payment Wilby didn't approve.
payment.clearedA bank debit cleared.
payment.returnedA bank debit came back (returned by the bank).
refund.waiting_for_bankA refund is waiting for a bank debit to clear first.
charge.approvalWilby decided on a charge (approved or not).
incremental_charge.requestedYou asked the customer to approve an incremental charge.
incremental_charge.approvedThe customer (or their rule) approved an incremental charge. Approved means yes, not that money moved.
incremental_charge.declinedThe customer declined an incremental charge.
incremental_charge.expiredThe customer didn't answer in time.
incremental_charge.charge_failedCharging an approved incremental charge failed.
incremental_charge.cancelledThe store withdrew an incremental charge.
authorization.captured_earlyA hold was captured early because it was about to expire.
authorization.reauthorizedA hold was renewed.
authorization.expiredA hold expired at the processor.
authorization.expiring_soonA hold will expire soon.
tip.addedThe customer added a tip.
evidence.addedEvidence was added to an order.
refund.goodwillA goodwill refund was recorded.
dispute.openedA dispute was opened.
dispute.sent_to_reviewA dispute was sent for review.
dispute.resolvedA dispute was settled.
dispute.chargeback_receivedThe processor reported a chargeback.
customer.code_requestedA customer asked for a one-time code: text it to them (when you text codes).
credential.issuedWilby issued a signed credential (permission) for a customer.