Webhooks

Every webhook event

115 event types. An endpoint subscribes to exact types, to a family with order.*, or to everything with *. Each type below has a page of its own with a complete example payload.

The ones most integrations need

order.paid: fulfil. Sent once, for paid or overpaid.
order.underpaid: the payer is being asked for the rest, or you can accept it.
order.expired and order.unpaid: stop fulfilment.
order.screening_hold: money arrived but order.paid is being held.
refund.confirmed.
For subscriptions: subscription.activated, subscription.renewed and subscription.unpaid.

New types may be added in any version, so an endpoint subscribed to * must ignore types it does not know.

Every event type

Each type is an anchor on this page: /docs/events#order.paid lands on order.paid.

`ping`

Events of the family ping
Event type	Sent when
`ping`	Sent by `POST /v1/webhook_endpoints/{id}/ping` and by the dashboard's "Send test event" button. `data.object` is `{"object": "ping", "endpoint": "we_…"}`.Carries `ping`

`checkout_session.*`

Events of the family checkout_session
Event type	Sent when
`checkout_session.created`	A session was created (API, payment link, invoice page, POS or subscription renewal).Carries `checkout_session`
`checkout_session.completed`	The session's order became `paid` or `overpaid`. Sent together with `order.paid`; handle one of them.Carries `checkout_session`
`checkout_session.expired`	The session's order expired unpaid, or the session was expired by the API.Carries `checkout_session`

`order.*`

Events of the family order
Event type	Sent when
`order.created`	An order was created by any source.Carries `order`
`order.processing`	The first payment for the order was seen. Not proof of payment: do not fulfil.Carries `order`
`order.paid`	The event to fulfil on. Sent once, the first time the order is paid in full with the confirmations its network needs: `status` is `paid` or `overpaid` (read it). The merchant wallet's own chain read shows the value. Also sent when an `underpaid` order is topped up or accepted, and when a late payment completes an `expired` or `cancelled` order (`paid_late: true`). For a high-value order `finalized` may be `false`; `order.finalized` follows.Carries `order`
`order.underpaid`	Less than the price arrived, beyond the 0.5% tolerance. The checkout offers the payer a top-up instruction for `amount_due` for 24 hours.Carries `order`
`order.overpaid`	More than the price arrived (beyond the over-tolerance), at first payment or by a later duplicate. Do not fulfil on this event: `order.paid` is the fulfilment event and was or is sent as well. This one tells you there is an excess in the merchant wallet to refund or keep as credit.Carries `order`
`order.finalized`	High-value orders only (above US$10,000 on Ethereum and the rollups): the payments behind an order that was already `paid` are now final on the network. A shop shipping something expensive waits for this.Carries `order`
`order.updated`	A field changed without a more specific event: `description`, `reference`, `customer`, `metadata`, a flag such as `screening_hold` or `provider_refund_received`, or a move between `paid` and `overpaid` after `order.paid` was already sent.Carries `order`
`order.expired`	The order passed `expires_at` with nothing credited. A late payment can still arrive for 30 days: the order then returns to `processing` and `order.paid` follows with `paid_late: true`.Carries `order`
`order.cancelled`	The order was cancelled by the API, the dashboard or a voided invoice. If a payer pays it anyway it returns to `processing`.Carries `order`
`order.refunded`	Confirmed refunds now equal `amount_paid`. `status` stays `paid`.Carries `order`
`order.partially_refunded`	A refund smaller than the remaining paid amount was confirmed.Carries `order`
`order.overpayment_resolved`	The excess was refunded (`refunded`) or kept as credit (`kept_as_credit`).Carries `order`
`order.payment_reverted`	A credited payment was undone by a chain reorganisation. Sent for any order that loses credit this way. Rare: confirmation counts are chosen to make it so.Carries `order`
`order.unpaid`	Follows `order.payment_reverted` when the order had been `paid` or `overpaid` and no longer is. Stop fulfilment if you still can.Carries `order`
`order.screening_hold`	The order's money has arrived and been credited, but a payer address screened as `review` or `blocked`, or could not be screened yet (`pending`), so `order.paid` is being withheld. `screening_hold` is true and `screening.status` says which. Do not fulfil. Sent at once.Carries `order`
`order.screening_released`	The hold ended: a member marked a `review` as reviewed (`reviewed`), the check could not be made for 60 minutes (`unchecked`), it came back `clear`, or Orrerie cleared a false positive. `order.paid` follows immediately. A `blocked` order is never released by the merchant.Carries `order`

`payment_instruction.*`

Events of the family payment_instruction
Event type	Sent when
`payment_instruction.created`	A payer chose an asset and was shown an address (or opened Pay with Orrerie).Carries `payment_instruction`
`payment_instruction.detected`	The payer's transfer to the instruction's address was seen.Carries `payment_instruction`
`payment_instruction.delivered`	The value reached the merchant wallet (wallet's own chain read).Carries `payment_instruction`
`payment_instruction.refunded_by_provider`	Relay could not route the deposit and returned it to the merchant's own wallet on the payer's network. The order is not credited; the merchant should refund the payer.Carries `payment_instruction`
`payment_instruction.failed`	The route failed and no provider refund has been seen. Needs the merchant's attention; reconciliation keeps reading it.Carries `payment_instruction`
`payment_instruction.expired`	The 15-minute window passed with nothing seen. The address is still re-read hourly until `late_until`.Carries `payment_instruction`

`payment.*`

Events of the family payment
Event type	Sent when
`payment.seen`	A transfer was seen in the mempool or its first block. A hint, never proof.Carries `payment`
`payment.confirmed`	The payer's transfer reached the network's confirmation count.Carries `payment`
`payment.settled`	The value is in the merchant wallet.Carries `payment`
`payment.reverted`	A block reorganisation removed the transfer. If its order was paid only by this payment, the order returns to `processing` or `open` and `order.payment_reverted` is sent.Carries `payment`
`payment.unmatched`	Money reached a merchant wallet and matches no order.Carries `payment`
`payment.screening_flagged`	The sender address screened as `review` or `blocked`, including a hit found later on a payment that was first released as clear or unchecked. The money is in the merchant's wallet either way.Carries `payment`

`refund.*`

Events of the family refund
Event type	Sent when
`refund.created`	A refund is `awaiting_approval`: requested by the API or a member, or the payer has just given the address through the claim link. Owners and Finance members are notified.Carries `refund`
`refund.signed`	A key-holding member approved with a passkey and the co-signer added its signature. From here it cannot be cancelled.Carries `refund`
`refund.sent`	The transaction was broadcast.Carries `refund`
`refund.confirmed`	The transaction reached its confirmation count. For a delivery through Relay, the destination received the value.Carries `refund`
`refund.failed`	The transaction failed on chain or the route failed and the funds are back in the merchant wallet. The reserve is released. Failure codes are in the failure codes of money out.Carries `refund`
`refund.unknown`	The outcome could not be established (for example a broadcast timed out). Do not request it again. Reconciliation keeps reading the chain and will send `.confirmed` or `.failed`.Carries `refund`
`refund.cancelled`	Ended before signing: by the API (`cancelled_by_api`), by a member rejecting it (`rejected_by_member`), or because its saved address was removed (`destination_removed`). The reserve is released.Carries `refund`
`refund.approval_lapsed`	Nobody approved within 7 days. The request is back in `draft` and its reserve is released; send it again with `POST .../submit` or cancel it.Carries `refund`
`refund.address_requested`	A refund was requested without an address, and its single-use claim link was made. Orrerie emails no payer in this release: the dashboard shows the link for you to give the payer. When they use it, `refund.created` follows with `awaiting_approval`.Carries `refund`
`refund.address_lapsed`	The payer gave no address within 14 days.Carries `refund`

`payout.*`

Events of the family payout
Event type	Sent when
`payout.created`	A payout is `awaiting_approval`: requested by the API or a member. Owners and Finance members are notified.Carries `payout`
`payout.signed`	A key-holding member approved with a passkey and the co-signer added its signature. From here it cannot be cancelled.Carries `payout`
`payout.sent`	The transaction was broadcast.Carries `payout`
`payout.confirmed`	The transaction reached its confirmation count. For a delivery through Relay, the destination received the value.Carries `payout`
`payout.failed`	The transaction failed on chain or the route failed and the funds are back in the merchant wallet. The reserve is released. Failure codes are in the failure codes of money out.Carries `payout`
`payout.unknown`	The outcome could not be established (for example a broadcast timed out). Do not request it again. Reconciliation keeps reading the chain and will send `.confirmed` or `.failed`.Carries `payout`
`payout.cancelled`	Ended before signing: by the API (`cancelled_by_api`), by a member rejecting it (`rejected_by_member`), or because its saved address was removed (`destination_removed`). The reserve is released.Carries `payout`
`payout.approval_lapsed`	Nobody approved within 7 days. The request is back in `draft` and its reserve is released; send it again with `POST .../submit` or cancel it.Carries `payout`

`conversion.*`

Events of the family conversion
Event type	Sent when
`conversion.created`	A conversion is `awaiting_approval`: requested by the API or a member. Owners and Finance members are notified.Carries `conversion`
`conversion.signed`	A key-holding member approved with a passkey and the co-signer added its signature. From here it cannot be cancelled.Carries `conversion`
`conversion.sent`	The transaction was broadcast.Carries `conversion`
`conversion.confirmed`	The transaction reached its confirmation count and the converted amount is in the destination wallet (wallet's own chain read).Carries `conversion`
`conversion.failed`	The transaction failed on chain or the route failed and the funds are back in the merchant wallet. The reserve is released. Failure codes are in the failure codes of money out.Carries `conversion`
`conversion.unknown`	The outcome could not be established (for example a broadcast timed out). Do not request it again. Reconciliation keeps reading the chain and will send `.confirmed` or `.failed`.Carries `conversion`
`conversion.cancelled`	Ended before signing: by the API (`cancelled_by_api`), by a member rejecting it (`rejected_by_member`), or because its saved address was removed (`destination_removed`). The reserve is released.Carries `conversion`
`conversion.approval_lapsed`	Nobody approved within 7 days. The request is back in `draft` and its reserve is released; send it again with `POST .../submit` or cancel it.Carries `conversion`

`payout_batch.*`

Events of the family payout_batch
Event type	Sent when
`payout_batch.created`	A batch was requested.Carries `payout_batch`
`payout_batch.processing`	The batch was approved; its rows are being signed and sent. Each row also emits its own `payout.*` events.Carries `payout_batch`
`payout_batch.completed`	Every row is final. `status` is `completed` (all rows `confirmed`) or `completed_with_failures`; read `counts`.Carries `payout_batch`
`payout_batch.needs_attention`	At least one row is `unknown`. Do not re-send that row; the batch leaves this state when evidence settles it.Carries `payout_batch`
`payout_batch.cancelled`	The batch was withdrawn or rejected before approval.Carries `payout_batch`

`saved_address.*`

Events of the family saved_address
Event type	Sent when
`saved_address.created`	A saved address was proposed.Carries `saved_address`
`saved_address.approved`	A key-holding member approved it; the 24-hour wait began.Carries `saved_address`
`saved_address.active`	The wait is over; payouts to it can be requested.Carries `saved_address`
`saved_address.removed`	It was removed.Carries `saved_address`

`invoice.*`

Events of the family invoice
Event type	Sent when
`invoice.created`	A draft was created.Carries `invoice`
`invoice.finalized`	The invoice got its number, order and page.Carries `invoice`
`invoice.sent`	The invoice email was accepted for sending.Carries `invoice`
`invoice.overdue`	The due date passed unpaid (at the end of that day in the merchant's time zone).Carries `invoice`
`invoice.paid`	The invoice's order became `paid` or `overpaid`.Carries `invoice`
`invoice.voided`	The invoice was voided.Carries `invoice`

`payment_link.*`

Events of the family payment_link
Event type	Sent when
`payment_link.created`	A link was created.Carries `payment_link`
`payment_link.updated`	A link was changed.Carries `payment_link`
`payment_link.deactivated`	The link was switched off, reached `max_uses` or passed `expires_at`.Carries `payment_link`

`product.*`

Events of the family product
Event type	Sent when
`product.created`	A product was created.Carries `product`
`product.updated`	A product was changed or archived.Carries `product`

`price.*`

Events of the family price
Event type	Sent when
`price.created`	A price was created.Carries `price`
`price.updated`	A price was archived or renamed.Carries `price`

`customer.*`

Events of the family customer
Event type	Sent when
`customer.created`	A customer was created by the API, the dashboard or a checkout that collected an email.Carries `customer`
`customer.updated`	A customer was changed, including a new refund address or a change of `credit_balance`.Carries `customer`
`customer.deleted`	A customer's personal data was erased. `data.object` is `{id, object, deleted}`.Carries `customer (deleted)`

`subscription.*`

Events of the family subscription
Event type	Sent when
`subscription.created`	A subscription was created with its first order.Carries `subscription`
`subscription.activated`	The first order was paid; the first period began.Carries `subscription`
`subscription.renewal_due`	The next period's order was created (7 days before the period end by default). Orrerie emails no customer in this release: send the customer that order's pay link yourself. Sent again, for the same order, on each later reminder day while it is unpaid.Carries `subscription`
`subscription.renewed`	A period order was paid. The new period starts at the old period end if paid by the end of grace, otherwise at the time of payment, and runs for the periods bought.Carries `subscription`
`subscription.past_due`	The period ended with its renewal order unpaid. The grace period runs.Carries `subscription`
`subscription.unpaid`	Grace ended unpaid and the renewal order expired. Withdraw access now. A later payment makes it `active` again.Carries `subscription`
`subscription.ended`	30 days passed in `unpaid`. Final.Carries `subscription`
`subscription.incomplete_expired`	The first order expired unpaid. Final; create a new subscription to try again.Carries `subscription`
`subscription.payment_reverted`	A payment on a period order was undone by the chain. The period dates went back and the state is `past_due` or `unpaid` by the dates.Carries `subscription`
`subscription.paused`	The subscription was paused.Carries `subscription`
`subscription.resumed`	The subscription was resumed.Carries `subscription`
`subscription.updated`	Items, reminder days, grace days, prepaid choices, proration, metadata or `cancel_at_period_end` changed.Carries `subscription`
`subscription.cancelled`	The subscription was cancelled, at once or at the period end.Carries `subscription`

`receipt.*`

Events of the family receipt
Event type	Sent when
`receipt.created`	A receipt was created for a paid order.Carries `receipt`

`wallet.*`

Events of the family wallet
Event type	Sent when
`wallet.deploying`	The wallet's first send was approved and its deployment transaction was broadcast.Carries `wallet`
`wallet.active`	The wallet is deployed and can send.Carries `wallet`

`fee_account.*`

Events of the family fee_account
Event type	Sent when
`fee_account.low`	A fee key fell below its low mark on a network. A send from that network would fail until it is topped up (from takings, or by hand).Carries `fee_account`
`fee_account.topped_up`	An order between US$1 and US$10 was delivered as the network's own coin to the fee account (its `order.paid` carries `settlement.recipient_kind: "fee_account"`), or a manual top-up arrived.Carries `fee_account`

`export.*`

Events of the family export
Event type	Sent when
`export.ready`	The export file can be downloaded.Carries `export`
`export.failed`	The export could not be built.Carries `export`

`merchant.*`

Events of the family merchant
Event type	Sent when
`merchant.tier_changed`	The tier changed (verification started, passed or failed).Carries `merchant`
`merchant.limit_approaching`	A volume limit reached 80% (sent once per limit per window). Read `usage` against `limits`.Carries `merchant`
`merchant.restricted`	New orders are switched off for this merchant. Withdrawals to saved addresses still work.Carries `merchant`
`merchant.unrestricted`	The restriction was lifted.Carries `merchant`

`member.*`

Events of the family member
Event type	Sent when
`member.invited`	A member was invited.Carries `member`
`member.joined`	An invitation was accepted.Carries `member`
`member.role_changed`	A member's role changed.Carries `member`
`member.removed`	A member was removed or an invitation revoked.Carries `member`

`api_key.*`

Events of the family api_key
Event type	Sent when
`api_key.created`	A key was created. The secret is never in an event.Carries `api_key`
`api_key.rolled`	A key was rolled; `data.object` is the old key, now with an end time.Carries `api_key`
`api_key.revoked`	A key was revoked or reached `expires_at`.Carries `api_key`

`webhook_endpoint.*`

Events of the family webhook_endpoint
Event type	Sent when
`webhook_endpoint.disabled`	Deliveries to an endpoint failed for 7 days running and it was switched off. Sent to the merchant's other endpoints; the Owners are emailed.Carries `webhook_endpoint`