# Webhook event reference

This page describes what Ripple Custody (Wallet) sends to your webhook endpoint: the envelope that wraps every delivery, and, for each subscription domain, what triggers an event and what the payload contains. For how to verify, acknowledge, and process deliveries, see [Receive webhook deliveries](/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries).

| Domain | Triggered when | Payload |
|  --- | --- | --- |
| `TRANSACTION` | A transaction status changes (transfers, deposits, withdrawals) | Transaction object |
| `WALLET` | A wallet status changes (creation, provisioning) | Wallet object |
| `APPROVAL` | An approval request is created or updated | Approval object |


## Envelope

Ripple Custody (Wallet) delivers each webhook message as a `POST` request with `Content-Type: application/json`. The body is a JSON object with a base64-encoded payload:

| Field | Description |
|  --- | --- |
| `domain` | The subscription domain that the event belongs to: `TRANSACTION`, `WALLET`, or `APPROVAL`. |
| `timestamp` | A UTC timestamp for the event, in ISO 8601 format. |
| `payload` | The resource object, JSON-encoded and then base64-encoded. Decode it to read the resource. Verify the signature against this base64 string before you decode it. See [Verify the signature](/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries#verify-the-signature). |


The envelope has no event ID. To detect duplicate deliveries, use the resource's `id` and `updatedAt` inside the payload. See [Deduplicate deliveries](/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries#deduplicate-deliveries).

Each delivery also carries a `Signature` header that you use to verify that the payload is authentic. For example: `MEQCIGjBwNKzzfqK9/Rb3Q2OQCyCuUiOOQz7vZwQ9iqInz76AiB/bvRn5iNUAkeVT80/pwhQ2LUajE6Mb2JtGt2mRmJMpg==`

For example, a `WALLET` delivery:

```json
{
    "domain": "WALLET",
    "timestamp": "2025-05-08T14:15:37Z",
    "payload": "eyJpZCI6IjAxOTYxNTNiLTY3YmMtN2NkMy1iNTExLTM1NDM3M2QyODEzMCIsICJ2YXVsdElkIjoiMDE5NjE1MmQtNTI5NC03MzlkLTk5NDUtMmE0OTlmOWUzOTg5IiwgIm9yZ2FuaXphdGlvbklkIjoiMjFjODEzMTktNWI4My00NWY5LWI2NDgtNDIwNTUwODRhZjE1IiwgInF1b3J1bUlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwgImNyZWF0ZWRCeSI6ImE1NWRmOWUwLWUxNGEtNDQxMC1hOTgzLTEyYWZhZTQ2NjYyZiIsICJjcmVhdGVkQXQiOiIyMDI1LTA0LTA4VDExOjQ4OjU2Ljg5OTA4NloiLCAidXBkYXRlZEF0IjoiMjAyNS0wNC0wOFQxMTo0ODo1Ni45MDA0OTBaIiwgIm5hbWUiOiJld3FmZXciLCAiZGVzY3JpcHRpb24iOiIiLCAiYWRkcmVzcyI6IjB4NDY0NDMyMGYzMUQ2OTU4RWQ4NjAzRWI2NjYwNDQ5NTBBYTY5NzAyZSIsICJwdWJsaWNLZXkiOiIwNDgxY2IwMmU4MjFlNTVhMmM2MTk2ZmZkZTM4MGJhM2I0OTgxN2JkYmYwMmYzMTVkYzI4YjU2ZjcwNzkyZDU2ZTZhZGFjOTE3ZTdhZGFmODdmMTBjMDg4NDA4YThjNmEwZTZkMTgwNzkzYzA1MGMzZDBjODc3MWNiOWRkZjgyNThkIiwgImtleXN0b3JlIjoiSFNNIiwgImJsb2NrY2hhaW4iOiJBUkJJVFJVTSIsICJzZXR0aW5ncyI6e30sICJzdGF0dXMiOiJQUk9WSVNJT05FRCJ9"
}
```

Decode `payload` to get the resource object, which contains detailed information about the event. For a decoded wallet object, see [Wallet payload example](#wallet-payload-example).

## Transaction domain

You receive a webhook notification whenever a transaction transitions to a new status. The payload contains the full transaction object with its current state.

| Status | Description | Terminal? |
|  --- | --- | --- |
| `REQUESTED` | Transaction created | No |
| `POLICY_CHECK_PENDING` | Validating against policies and collecting any required approvals | No |
| `POLICY_CHECK_PASSED` | Policy checks and all required approvals passed | No |
| `COMPILATION_PENDING` | Preparing for blockchain | No |
| `COMPILED` | Ready for signing | No |
| `SIGNATURE_PENDING` | Waiting for signature | No |
| `SIGNED` | Signed successfully | No |
| `PUBLISH_PENDING` | Submitting to network | No |
| `PUBLISHED` | Submitted to blockchain | No |
| `CONFIRMATION_PENDING` | Awaiting block confirmation | No |
| `CONFIRMED` | Confirmed on blockchain | ✅ Yes |
| `REJECTED` | Rejected by policy or approval | ✅ Yes |
| `FAILED` | Technical failure | ✅ Yes |


For more details on transaction status flow, see [How transactions work](/products/wallet/transactions).

### Transaction payload example

```json
{
  "domain": "TRANSACTION",
  "timestamp": "2025-05-08T14:30:00Z",
  "payload": "base64-encoded-transaction-object"
}
```

When decoded, the payload contains the transaction object. Key fields include:

```json
{
  "id": "019c94f1-cc8c-79b4-9c0f-bc7edaabc267",
  "vaultId": "0196152d-5294-739d-9945-2a499f9e3989",
  "walletId": "0196153b-67bc-7cd3-b511-354373d28130",
  "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
  "status": "CONFIRMED",
  "blockchain": "ETHEREUM",
  "hash": "0x8a4c5e9f2b1d7c3a6e8f0b2d4c6a8e0f2b4d6c8a0e2f4b6d8c0a2e4f6b8d0c2e",
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2E8Ba"
  },
  "asset": {
    "symbol": "ETH"
  },
  "qty": "1.500000000000000000",
  "createdAt": "2025-05-08T14:25:00Z",
  "updatedAt": "2025-05-08T14:30:00Z"
}
```

For the complete transaction schema, see the [Transaction API reference](/products/wallet/api-docs/palisade-api/palisade-api/transactions/transactionsservice_gettransaction).

Inbound transactions and compliance
For inbound transactions, the payload may include a `freezeInfo` field indicating whether funds are frozen for compliance review. See [Transaction Freeze and Compliance Controls](/products/wallet/changelogs/transaction-freeze-and-compliance-controls) for details.

## Wallet domain

You receive a webhook notification whenever a wallet transitions to a new status. The payload contains the full wallet object with its current state.

| Status | Description | Terminal? |
|  --- | --- | --- |
| `CREATED` | Wallet record created | No |
| `PROVISIONING` | Wallet being set up | No |
| `PROVISIONED` | Wallet ready for use | ✅ Yes |
| `PROVISIONING_FAILED` | Setup failed | ✅ Yes |


### Wallet payload example

The envelope's `domain` is `WALLET`; see the example in [Envelope](#envelope). When decoded, the payload contains the wallet object. For example:

```json
{
  "id": "0196153b-67bc-7cd3-b511-354373d28130",
  "vaultId": "0196152d-5294-739d-9945-2a499f9e3989",
  "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
  "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
  "createdAt": "2025-04-08T11:48:56.899086Z",
  "updatedAt": "2025-04-08T11:48:56.900490Z",
  "name": "My Wallet",
  "address": "0x4644320f31D6958Ed8603Eb666044950Aa69702e",
  "publicKey": "0481cb02e821e55a2c6196ffde380ba3b49817bdbf02f315dc28b56f70792d56e6adac917e7adaf87f10c088408a8c6a0e6d180793c050c3d0c8771cb9ddf8258d",
  "keystore": "HSM",
  "blockchain": "ARBITRUM",
  "settings": {},
  "status": "PROVISIONED"
}
```

For the complete wallet schema, see the [Wallet API reference](/products/wallet/api-docs/palisade-api/palisade-api/wallets/vaultservice_getwallet).

## Approval domain

You receive a webhook notification whenever an approval request is created or updated. This includes approvals for transactions, policy changes, and user management actions.

The payload contains the approval request with its current state: the overall status of the approval set, and the status of each approver's response.

### Approval set status

The overall approval request status:

| Status | Description | Terminal? |
|  --- | --- | --- |
| `PENDING` | Waiting for approvers to respond | No |
| `MET` | Required approvals received | ✅ Yes |
| `NOT_MET` | Approval rejected | ✅ Yes |
| `EXPIRED` | Timed out before requirements met | ✅ Yes |
| `FAILED` | Technical failure during processing | ✅ Yes |


### Individual approval status

Each approver's response within an approval set:

| Status | Description |
|  --- | --- |
| `PROCESSING` | Approver is reviewing the request |
| `APPROVED` | Approver approved the request |
| `REJECTED` | Approver rejected the request |


## Related topics

- [Webhooks](/products/wallet/integrations-and-monitoring/webhooks) — What webhooks are, how delivery works, and webhooks compared with audit logging
- [Receive webhook deliveries](/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries) — Verify signatures, handle retries, and process events safely
- [Manage webhooks via the API](/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks-api) — Subscribe a webhook to domains