Payout Webhook (`payout.updated`)

When a payout reaches a terminal state (success or cancelled), Pexx sends a single payout.updated webhook to your configured endpoint.

Read Webhook Overview first for how to receive requests, verify signatures (X-Webhook-Signature), handle retries, and respond within 15 seconds.

Event type

Field	Value
`group`	`payout`
`type`	`payout.updated`

Trigger: A payout’s status changes to a terminal value.

Scope: This event type is payout-only. It replaces any legacy transaction.* webhook naming for payouts; those legacy types are being phased out.

Payload (`data`)

The JSON object under the envelope’s data key has the following shape. Field names are camelCase in the wire format.

Field	Type	Description
`merchantReferenceId`	string	The `merchantReferenceId` you supplied when you created the payout request. Use it to correlate this webhook with your internal order or payout record.
`payoutId`	string	The `payoutId` Pexx returned when the payout was created. Globally unique on the Pexx side.
`status`	string	Terminal payout status. Only the values below are emitted over webhooks.

`status` values (terminal only)

Value	Meaning
`PAID`	Payout completed successfully.
`CANCELLED`	Payout was cancelled; no further updates.

Example

HTTP headers (representative)

Content-Type: application/json
X-Webhook-Event-Id: 9c4f8a72-3e71-4f4a-bc2a-1f0d8b8e1a91
X-Webhook-Event-Type: payout.updated
X-Webhook-Timestamp: 1745793600123
X-Webhook-Signature: sha256=<hex>

Request body

{
  "id": "9c4f8a72-3e71-4f4a-bc2a-1f0d8b8e1a91",
  "group": "payout",
  "type": "payout.updated",
  "occurred_at_ms": 1745793600000,
  "data": {
    "merchantReferenceId": "MRCH-20250428-000123",
    "payoutId": "PYT-9f2c8e1a-b4d5-4e6f-8a1c-2d3e4f5a6b7c",
    "status": "PAID"
  }
}

Recommended handling

Correlate using data.merchantReferenceId and/or data.payoutId to query the payout.
Idempotency: Use X-Webhook-Event-Id (same as envelope id) so duplicate deliveries are safe.
Ordering: Delivery order is not guaranteed across events. Prefer occurred_at_ms and your own state machine when reconciling; avoid blindly overwriting a newer terminal state with an older one if you detect regression.
Confirm via API: After you return 2xx, call Pexx’s payout / withdrawal query API (using data.payoutId or data.merchantReferenceId, depending on what your integration supports) to load the latest server-side state and reconcile it with the webhook. That way you still benefit from the webhook for timeliness, while treating the API response as the source of truth if anything disagrees.
Performance: Return 2xx quickly; persist the payload and run correlation, API queries, and any heavy logic asynchronously (see overview).

Payout Webhook (payout.updated)