The complete catalog of webhook events GIFQ sends, across both domains.
Every event GIFQ sends, in one table. They all share the transport, signing, and delivery rules on Overview.
There are 14 event names across two domains.
payout.* events report one payout moving through its lifecycle, split across crypto sends and gift cards. See Payout events.
recipient.* events report the recipient's entitlement as a whole. See Recipient events.
There is no subscription model. Every event below fires for any payout order that has a callback_url.
Routing
Three event names fire for both payout typesCrypto sends and gift cards share
payout.processing,payout.failed, andpayout.cancelled, and the bodies are structurally different. Route oneventandpayout_typetogether. Every other name belongs to exactly one payout type.
All events
| Event | Domain | payout_type | Fires when | Body |
|---|---|---|---|---|
payout.quote_created | payout | crypto | An FX quote is issued for a send | data |
payout.quote_confirmed | payout | crypto | The recipient confirms a cross-currency quote | data |
payout.quote_cancelled | payout | crypto | The recipient cancels an open quote | data |
payout.in_progress | payout | crypto | The send is accepted and no funds have moved | data |
payout.processing | payout | crypto | gift_cards | FX is in flight or the chain broadcast is pending, or a gift card has been requested from the brand | data | envelope |
payout.completed | payout | crypto | The send is finalized on chain | data |
payout.fulfilled | payout | gift_cards | A gift card was issued to the recipient | envelope |
payout.failed | payout | crypto | gift_cards | The send did not go through, or gift-card issuance failed | data | envelope |
payout.expired | payout | crypto | Nobody actioned the send inside its window | data |
payout.cancelled | payout | crypto | gift_cards | The send was cancelled with no funds moved, or a gift card was cancelled | data | envelope |
recipient.viewed | recipient | gift_cards | The recipient first opened their claim link | envelope |
recipient.partially_redeemed | recipient | gift_cards | The recipient redeemed some of their balance | envelope |
recipient.redeemed | recipient | crypto | gift_cards | The entitlement is fully redeemed | envelope |
recipient.expired | recipient | gift_cards | The entitlement lapsed with balance unspent | envelope |
Three names fire for both payout types and carry a different body for each. Their event pages split into Crypto and Gift cards sections.
data means the three-key crypto body of event, payout_type, and data. envelope means the flat gift-card body. See Two body shapes.
Events we do not send
These are worth knowing so you do not wait for something that never arrives.
| Not sent | Why |
|---|---|
recipient.sent | The 201 from POST /api/payout-orders already names every recipient. This event would carry about a third of total volume and tell you nothing new. |
| A reservation event | We reserve balance before calling the brand, and notify you at payout.fulfilled instead. A failed issuance therefore never leaves you holding a stale redemption. |
| A reversal event | A reservation that produced no event has nothing to unwind. Failed issuance arrives as payout.failed. |
Anything on draft crypto orders | payout.quote_created already covers that moment. |
Status values
Recipient statuses
pending, sent, viewed, partially_redeemed, redeemed, expired.
Only the last four emit events. redeemed and expired are terminal.
Gift-card payout statuses
processing, fulfilled, failed, cancelled.
All four emit events. fulfilled, failed, and cancelled are terminal for that card.
Crypto send statuses
in_progress, processing, completed, failed, expired, cancelled.
completed, failed, expired, and cancelled are terminal. A draft send emits nothing.
The event name does not always matchdata.statusOn crypto bodies the event name is GIFQ's status.
data.statusis the provider's own string, passed through untouched.Our provider's documented statuses line up with our event names one for one, apart from cancellation, where they use one
land we emitpayout.cancelled. A provider string we do not recognise is passed through indata.statusunchanged.Branch on the event name. Read
data.statusonly when you want the provider's wording, for a support ticket or an audit trail.
How to read an event page
Every event page follows the same order.
- Triggered when. The condition that produces the event.
- Body. Which of the two shapes it uses, and the identifiers it carries.
- Event-specific fields. Only what this event adds on top of the shared shape.
- Example. A complete JSON body.
- What to do on receipt. Recommended handling.