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.
| 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 |
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. |
The envelope has no event ID. To detect duplicate deliveries, use the resource's id and updatedAt inside the payload. See 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:
{
"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.
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.
{
"domain": "TRANSACTION",
"timestamp": "2025-05-08T14:30:00Z",
"payload": "base64-encoded-transaction-object"
}When decoded, the payload contains the transaction object. Key fields include:
{
"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.
For inbound transactions, the payload may include a freezeInfo field indicating whether funds are frozen for compliance review. See Transaction Freeze and Compliance Controls for details.
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 |
The envelope's domain is WALLET; see the example in Envelope. When decoded, the payload contains the wallet object. For example:
{
"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.
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.
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 |
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 |
- Webhooks — What webhooks are, how delivery works, and webhooks compared with audit logging
- Receive webhook deliveries — Verify signatures, handle retries, and process events safely
- Manage webhooks via the API — Subscribe a webhook to domains