payout.status

Fired on every payout state change. Settle your own ledger row by the ref you supplied on POST /payouts. status is the new payout status; terminal states are paid and returned.

You subscribe to specific event types when your client is provisioned. An event type you are not subscribed to is recorded but never delivered.

Signature. Same scheme as payee.updated: verify x-8x-signature = HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}") before trusting the body. Reject deliveries whose x-8x-timestamp is more than 5 minutes (300s) from now — verifyWebhook enforces this. Delivery is at-least-once — a webhook may arrive more than once, so process by (transactionId, status) idempotently. Return any 2xx to acknowledge.

Header Parameters

x-8x-timestamp*string

Unix time (seconds) at which the gateway signed this webhook delivery.

x-8x-signature*string

Hex HMAC-SHA256(signingSecret, "{x-8x-timestamp}.{rawBody}") over the raw delivery body. Verify it before trusting the payload.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Webhook body for payout.status.

type*string

transactionId*string

Formatuuid

ref*|

Your original ref, so you can settle your own ledger row.

status*|

Which vocabulary you get depends on your client's status version: PayoutStatus for version 1 (the default), PayoutStatusV2 for version 2.

providerRef*string|null

externalId*string

Your own stable payee id (payees.external_id), so you can join this event to the creator in your system — e.g. resolve their Discord id and DM them.

payeeId*string

The gateway's payee id.

Formatuuid

amountCents*integer

The payout amount in integer cents.

currency*string

provider*|

The rail this payout went out on; null before routing.

claimUrl*|

The creator's claim link (Grade) when they must act; null on rails without one. The gateway emails it to the creator for payouts created by POST /payouts and for owed-balance releases and withdrawals. It does not email after POST /payouts/{id}/release, POST /payouts/{id}/retry or a batch row, so keep the webhook's copy and show it to the creator yourself.

failureKind*|

Structured failure category, set on a failed/held transition; null otherwise.

settledAt*|

True bank-settlement time, or null. paid does NOT imply this is set. settledAt is stamped only on a genuine bank-settlement signal, which several rails never emit for electronic payouts: Tipalti stamps it only on CLEARED (paper checks); Grade only when a non-null landedDate appears. For those rails a payout can stay paid with settledAt: null indefinitely. Key off settledAt, not status: paid, when you need confirmed bank arrival.

Formatdate-time

occurredAt*string

Formatdate-time

liftingFeeCents?|

Present only on a returned event — the provider return/lifting fee (cents). Null on other statuses.

restoredCents?|

Present only on a returned event — net cents put back to the payee's balance after the bounce. Render this rather than re-deriving it.

Response Body

Example Requests

POST/payout.status

Header Parameters

Request Body

Response Body

2XX

Request Bodyapplication/json

Header Parameters