payee.updated
Fired when a payee's onboarding state changes — typically when they finish
onboarding and become payable. Map it back to your own record via
externalId. (Tipalti payability is discovered by the gateway's reconcile
polling, so this can arrive shortly after the payee finishes, not instantly.)
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. The gateway POSTs to your registered webhook URL with
x-8x-timestamp and x-8x-signature headers, where the signature is
HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}"), hex-encoded — the same
scheme as outbound API requests. Verify before trusting the body
(PayoutClient.verifyWebhook does this). Reject deliveries whose x-8x-timestamp
is more than 5 minutes (300s) from now — verifyWebhook enforces this. Return
any 2xx to acknowledge; non-2xx (or a timeout) triggers retry with exponential
backoff.
Header Parameters
Unix time (seconds) at which the gateway signed this webhook delivery.
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 payee.updated.
Response Body
Example Requests
/payee.updatedLink released disbursements to their replacement payout POST
Attach several already-released owed rows to ONE already-submitted replacement payout. A **ledger repair only**: it never creates, retries, or calls a payout provider — it repairs the pre-consolidation fan-out shape, where a withdrawal released N disbursements as N one-row payouts and a single replacement payout was later submitted in their place. **Idempotent** — re-sending the same `(replacementTransactionId, disbursementIds)` returns `idempotentReplay: true` and links nothing twice. The replacement's amount must equal the sum of the linked rows, and every row must belong to the replacement's payee, or the call is rejected whole. **Required scope:** `disbursements:write`.
payout.status Webhook
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.