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>"
}
FieldNotes
urlHTTPS only, up to 2,048 characters. Private, loopback, and other non-public addresses are refused, including when they are reached through DNS.
eventsOne or more event types, or ["*"] for all of them.
vaultIdOptional. 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.

HeaderValue
webhook-idThe delivery ID. It stays the same across retries.
webhook-timestampUnix seconds when this attempt was sent.
webhook-signaturev1,<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-idThe 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.

AttemptDelay before it
1Immediately
210 seconds
330 seconds
42 minutes
510 minutes
61 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-id you have processed for at least 24 hours, and skip repeats.
  • Don't rely on arrival order. Retries can overtake newer events. Use time and, for operation.updated, data.version to keep the latest state.
  • Acknowledge quickly and do slow work afterwards, so deliveries don't time out.

Delivery logs and redelivery

EndpointUse
GET /v2/webhooks/subscriptions/{id}/deliveriesList a subscription's deliveries, filtered by status (pending, in_flight, succeeded, failed, or dead).
GET /v2/webhooks/deliveries/{deliveryId}/attemptsSee each attempt's response code, error, and the start of the response body.
POST /v2/webhooks/deliveries/{deliveryId}/redeliverSend 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.


Did this page help you?