A webhook is a subscription that tells Ripple Collections to notify your system when something happens, instead of you polling to find out.
You register a callback URL against an event type. When an event of that type occurs, we send an HTTP request to your URL carrying the event payload. This is how you track collections, settlements, and account activity in real time — a payer completing a payment, a settlement failing, an account balance changing.
Webhooks are created one per event type. Subscribing to several event types creates several webhook records, each independently retrievable and updatable.
Events are grouped by the resource they concern.
| Resource | Event types |
|---|---|
| Accounts | ACCOUNT_CREATED, ACCOUNT_STATUS_CHANGED, ACCOUNT_BALANCE_UPDATED |
| Channels | CHANNEL_CREATED, CHANNEL_ARCHIVED |
| Partners | PARTNER_STATUS_CHANGED |
| Transactions | TRANSACTION_STATUS_CHANGED |
| Settlements | SETTLEMENT_INITIATED, SETTLEMENT_COMPLETED, SETTLEMENT_FAILED |
| Wallet addresses | WALLET_ADDRESS_CREATED, WALLET_ADDRESS_ROTATED |
| Webhooks | WEBHOOK_CREATED, WEBHOOK_UPDATED, WEBHOOK_DELETED |
Anyone can send an HTTP request to your callback URL. Signature verification is how you establish that a given request actually originated from Ripple Collections and was not tampered with in transit.
When you create a webhook, the response includes a signature_verification_key. This is a base64-encoded symmetric secret, and it is returned at creation time — persist it securely then, because it is what you use to validate every subsequent payload.
Each delivered webhook carries a timestamp header and an HMAC-SHA256 signature computed over the payload. Your handler recomputes the signature using your stored key and compares.
Treat this as required rather than optional. An unverified webhook endpoint will act on anything sent to it.
For the verification procedure and code samples, see Verify webhook signatures.
- Create webhooks: Create one webhook per event type supplied.
- List webhooks: Retrieve your existing webhook subscriptions.
- Get a webhook: View the details of a single webhook subscription.
- Update a webhook: Change an existing subscription, for example to move it to a new callback URL.
- Delete a webhook: Remove a webhook subscription you no longer need.