Skip to main content
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.created
  • payout.processing
  • payout.completed
  • payout.failed
  • payout.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.