Platform Payouts writes a webhook event in the same transaction as each public
status transition. Delivery is at least once and ordering is not guaranteed.
Event types
payout.createdpayout.processingpayout.completedpayout.failedpayout.reversed
Payload
data.payout uses the same public projection as the API. It does not include
full account numbers, encrypted beneficiary material, internal errors, or
execution credentials.
Verify the request
Webhook requests include:
Build the canonical string exactly as described in
Authentication, using the webhook endpoint path including its query string and
the SHA-256 hash of the exact raw body bytes. Verify with the outbound webhook
secret issued for the endpoint—not the API signing secret. Use a constant-time
comparison, enforce a timestamp window, and reject repeated nonces.
Do not parse and re-serialize JSON before verifying. Even equivalent JSON
produces a different signature when its bytes differ.
Delivery contract
- Return
2xx only after the event is durably stored.
- Deduplicate by
webhook_event_id.
- A
4xx response is treated as a permanent endpoint or contract failure.
- Network and
5xx failures are retried with backoff, then dead-lettered for
operator replay after the configured attempt limit.
- Tolerate duplicate and out-of-order events. Fetch
GET /v1/payouts/{id} for authoritative current state.
