> For the complete documentation index, see [llms.txt](https://docs.calypso.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calypso.money/payouts/payout-webhooks.md).

# Payout webhooks

**Webhook events**

| Event type                | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| PAYOUT\_CHANGE\_STATUS    | Payout has changed state to In Progress, Canceled, Failed, Partial or Completed |
| PAYOUT\_CONFIRMED         | Payout has changed state to Confirmed                                           |
| PAYOUT\_HASH\_RECEIVED    | Payout has received a hash but has not yet received all network confirmations.  |
| PAYOUT\_VALIDATION\_ERROR | Validation error has occurred during payout processing                          |

**Payload description**

**PAYOUT\_CHANGE\_STATUS**

| Parameter        | Type   | Description                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------ |
| hash             | string | transaction hash.                                                        |
| type             | string | event type: PAYOUT\_CHANGE\_STATUS.                                      |
| parentExternalId | number | system id of the payout.                                                 |
| createdDate      | string | date and time of payout creation.                                        |
| payoutStatus     | string | current state of the payout.                                             |
| idempotencyKey   | string | the external id that was generated while payout creating through api.    |
| currency         | string | currency of the payout.                                                  |
| externalId       | string | External identifier passed by the merchant when creating the transaction |

**PAYOUT\_CONFIRMED**

| Parameter        | Type   | Description                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------ |
| type             | string | event type: PAYOUT\_CONFIRMED.                                           |
| parentExternalId | number | system id of the payout.                                                 |
| createdDate      | string | date and time of payout creation.                                        |
| approved         | array  | list of users who approved the payout.                                   |
| idempotencyKey   | string | the external id that was generated while payout creating through api.    |
| currency         | string | currency of the payout                                                   |
| externalId       | string | External identifier passed by the merchant when creating the transaction |

**PAYOUT\_HASH\_RECEIVED**

| Parameter        | Type   | Description                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------ |
| hash             | string | transaction hash.                                                        |
| type             | string | event type: PAYOUT\_HASH\_RECEIVED.                                      |
| parentExternalId | number | system id of the payout.                                                 |
| createdDate      | string | date and time of payout creation.                                        |
| payoutStatus     | string | current state of the payout.                                             |
| idempotencyKey   | string | the external id that was generated while payout creating through api.    |
| currency         | string | currency of the payout.                                                  |
| externalId       | string | External identifier passed by the merchant when creating the transaction |

**PAYOUT\_VALIDATION\_ERROR**

| Parameter        | Type   | Description                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------ |
| type             | string | event type: PAYOUT\_VALIDATION\_ERROR.                                   |
| parentExternalId | number | system id of the payout.                                                 |
| message          | string | validation error message.                                                |
| createdDate      | string | date and time of payout creation.                                        |
| dealWithdrawalId | number | system id of withdrawal where validation error occured.                  |
| validationStatus | string | the reason of validation error.                                          |
| idempotencyKey   | string | the external id that was generated while payout creating through api.    |
| currency         | string | currency of the payout.                                                  |
| externalId       | string | External identifier passed by the merchant when creating the transaction |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.calypso.money/payouts/payout-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.