Webhooks
Receive webhooks when your vault's addresses, transactions, and requests change
io.vault webhooks are signed HTTPS POST requests to a URL you control, each carrying one event. Use them to react to deposits, track your transaction requests, and follow transactions to finality without polling.
io.vault webhooks come from Treasury and Tokenisation. io.sign sends its own events, such as vault and signer changes, through io.sign webhooks.
Subscribe
To add and manage subscriptions without code, use the io.finnet dashboard. See Webhooks in the dashboard. To use the API, follow this section.
Create a subscription with POST /v2/webhooks/subscriptions:
{
"url": "https://hooks.example.com/io-vault",
"events": ["wallet.receiveToken", "transaction.finalized", "operation.updated"],
"vaultId": "<vault-id>"
}| Field | Notes |
|---|---|
url | HTTPS only, up to 2,048 characters. Private, loopback, and other non-public addresses are refused, including when they are reached through DNS. |
events | One or more event types, or ["*"] for all of them. |
vaultId | Optional. Set it to receive only that vault's events. Leave it out to receive events for every vault in your organisation. |
Your organisation can have up to 100 subscriptions. You can list, update, and delete them under /v2/webhooks/subscriptions. To change one, send PATCH /v2/webhooks/subscriptions/{id} with the fields to change. Set status to paused to stop deliveries and to active to start them again. Set vaultId to null to receive events for every vault. Pausing or deleting a subscription stops new deliveries, but deliveries already queued are still sent.
What a delivery looks like
Each delivery is a POST whose body is a CloudEvents 1.0 event:
{
"specversion": "1.0",
"id": "<event-id>",
"source": "vault-treasury",
"type": "wallet.receiveToken",
"subject": "<chain>:<transaction-hash>:<address>",
"time": "2026-09-01T10:22:31.004Z",
"datacontenttype": "application/json",
"organisationid": "<organisation-id>",
"workspaceid": "<organisation-id>",
"data": { "...": "event fields" }
}source is vault-treasury or vault-tokenisation. The data fields for each event are in Webhook events.
Verify the signature
When signing is enabled in your environment, every delivery is signed using the Standard Webhooks scheme, the same as io.sign webhooks. Without it, deliveries are unsigned and the secret endpoints return 409 with SIGNING_NOT_CONFIGURED. io.finnet configures signing for each deployment, and you can't turn it on yourself. If you get this error, contact [email protected] to have signing enabled, and don't accept unsigned deliveries in production.
| Header | Value |
|---|---|
webhook-id | The delivery ID. It stays the same across retries. |
webhook-timestamp | Unix seconds when this attempt was sent. |
webhook-signature | v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<raw body>. It can hold several space-separated signatures, one for each valid secret, for example during a secret rotation. Accept the delivery if any of them matches. |
x-webhook-delivery-id | The delivery ID, for your logs. |
Get the subscription's whsec_ secret from GET /v2/webhooks/subscriptions/{id}/secret, and rotate it with POST /v2/webhooks/subscriptions/{id}/secret/rotate. After a rotation, both secrets are valid for 24 hours.
Verify the signature against the raw request body before you parse it, reject timestamps more than 5 minutes old, and compare signatures in constant time. The io.sign verification guide has a Node.js example that works for io.vault webhooks too. Use your io.vault subscription's secret, not an io.sign one.
Respond, retries, and duplicates
Return any 2xx status within 10 seconds to acknowledge a delivery. Anything else, including redirects, timeouts, and 4xx responses, is retried.
| Attempt | Delay before it |
|---|---|
| 1 | Immediately |
| 2 | 10 seconds |
| 3 | 30 seconds |
| 4 | 2 minutes |
| 5 | 10 minutes |
| 6 | 1 hour |
Each delay includes up to 20% random jitter. After the sixth failed attempt, the delivery is marked dead and isn't retried automatically.
Deliveries are at least once and not in order:
- Store each
webhook-idyou have processed for at least 24 hours, and skip repeats. - Don't rely on arrival order. Retries can overtake newer events. Use
timeand, foroperation.updated,data.versionto keep the latest state. - Acknowledge quickly and do slow work afterwards, so deliveries don't time out.
Delivery logs and redelivery
| Endpoint | Use |
|---|---|
GET /v2/webhooks/subscriptions/{id}/deliveries | List a subscription's deliveries, filtered by status (pending, in_flight, succeeded, failed, or dead). |
GET /v2/webhooks/deliveries/{deliveryId}/attempts | See each attempt's response code, error, and the start of the response body. |
POST /v2/webhooks/deliveries/{deliveryId}/redeliver | Send a delivery again now, with a fresh set of attempts. It keeps the same webhook-id. |
After an outage on your side, list your dead deliveries and redeliver them. A redelivery keeps its webhook-id, so it can't make a receiver that deduplicates on webhook-id process an event again. Redeliver only deliveries your receiver didn't process.
Updated 3 days ago