Webhooks
Deliver io.sign events to URLs you control
The webhooks service delivers events to URLs you control. It runs as its own process, separate from the four signing-service components described in Configuring io.sign, and listens on port 3010 by default. When a subscribed event fires, the service sends a POST with a JSON event payload to your configured HTTPS URL.
On io.finnet-managed deployments, you can manage webhooks in the io.finnet dashboard. See Webhooks in the dashboard. On any deployment, you can manage them through the REST API.
Manage subscriptions through the API
| Action | Endpoint |
|---|---|
| Create a subscription | POST /v1/webhooks |
| List subscriptions | GET /v1/webhooks |
| Get a subscription | GET /v1/webhooks/{id} |
Change its url, events, vaultId, or status | PATCH /v1/webhooks/{id} |
| Delete a subscription | DELETE /v1/webhooks/{id} |
A subscription belongs to an organisation and specifies its events and destination URL:
urlmust use HTTPS, be at most 2,048 characters, contain no credentials, and not point to a private or reserved address.eventslists at least one event type.vaultIdrestricts signature, reshare, and vault events to one vault. Leave it out for organisation-wide delivery, or set it tonullin aPATCHto widen an existing subscription.signer.createdis organisation-wide only, so a subscription with avaultIdnever receives it.statusisactive,paused, ordisabled. Onlyactivesubscriptions receive new deliveries.
Supported events
| Event family | Supported event types |
|---|---|
| Signatures | signature.created, signature.presigning, signature.signing, signature.completed, signature.rejected, signature.failed, signature.expired, signature.cancelled |
| Reshares | reshare.created, reshare.presigning, reshare.signing, reshare.completed, reshare.rejected, reshare.failed, reshare.expired, reshare.cancelled |
| Vaults | vault.created, vault.activated, vault.archived, vault.unarchived, vault.deleted |
| Signers | signer.created |
Set events to ["*"] to receive every event type.
Authenticating deliveries
When your deployment has signing turned on, io.sign signs every delivery with a hash-based message authentication code using SHA-256 (HMAC-SHA256), following Standard Webhooks v1. Your receiver uses the subscription's secret to verify the request body and signed headers before processing the event.
Start with Set up webhook signing to enable signing, create a subscription, retrieve its secret, and check your receiver. Use Verify webhook signatures for the Node.js example, replay protection, and secret rotation.
Confirm with your operator whether signing is active, and record that requirement in your receiver's configuration. Once signing is on, reject requests that lack any signature header. A deployment without a signing root key sends unsigned deliveries. Never let the presence or absence of headers decide whether your receiver verifies a request.
Keep the endpoint on HTTPS and store subscription secrets in your secret manager.
Delivery retries
The built-in delivery worker makes up to six attempts per delivery by default: the initial attempt and five retries. A successful HTTP 2xx response completes the delivery. Non-2xx responses, including 4xx and 5xx, and network failures or timeouts use the retry budget. The worker doesn't follow redirects, and counts them as failed attempts.
The default delays before retries are 10 seconds, 30 seconds, 120 seconds, 600 seconds, and 3600 seconds. Each delay starts after the failed attempt and includes an additional random delay of up to 20% to spread retries over time. Worker polling and load can delay the next attempt further. The worker does not use the receiver's Retry-After header to schedule retries.
Configure retries
For self-hosted deployments, set these environment variables on the webhooks service and restart or redeploy it. They apply to the built-in delivery worker. For io.finnet-managed deployments, ask io.finnet for the settings in your environment.
| Variable | Default | Behaviour |
|---|---|---|
WEBHOOKS_MAX_ATTEMPTS | 6 | Total attempt budget, including the initial attempt. Set to 1 to disable automatic retries after a failed attempt. |
WEBHOOKS_BACKOFF_SECONDS | 10,30,120,600,3600 | Comma-separated positive integers giving the delay before each retry, in seconds. If further retries remain after the list ends, the worker reuses the final delay. Each delay receives up to 20% additional random delay. |
WEBHOOKS_REQUEST_TIMEOUT_MS | 10000 | Timeout for an HTTP delivery attempt, in milliseconds. |
WEBHOOKS_POLL_INTERVAL_MS | 1000 | Delay between worker polls when the previous batch wasn't full, in milliseconds. |
WEBHOOKS_BATCH_SIZE | 25 | Maximum deliveries claimed and processed concurrently in one batch per worker. |
WEBHOOKS_LEASE_TTL_MS | 60000 | Time before an attempt left in progress can be reclaimed, in milliseconds. |
For example, this configuration allows four attempts in total, with retry delays of 30 seconds, 120 seconds, and 600 seconds, plus the additional random delay:
WEBHOOKS_MAX_ATTEMPTS=4
WEBHOOKS_BACKOFF_SECONDS=30,120,600
WEBHOOKS_REQUEST_TIMEOUT_MS=10000These are deployment settings. The subscription API has no per-subscription retry settings. The service stores the attempt budget when it creates each delivery, so changing WEBHOOKS_MAX_ATTEMPTS affects new deliveries. Existing deliveries retain their stored limit, including when manually redelivered.
Keep both WEBHOOKS_REQUEST_TIMEOUT_MS and WEBHOOKS_POLL_INTERVAL_MS below WEBHOOKS_LEASE_TTL_MS; invalid combinations fail configuration validation. If a worker stops during an attempt, recovery counts that attempt against the budget and waits at least another lease interval before retrying.
Inspect and redeliver failed deliveries
When the attempt budget runs out, the delivery has status dead and automatic retries stop. To diagnose the failure, list a subscription's deliveries with GET /v1/webhooks/{id}/deliveries, and a delivery's attempts with GET /v1/webhooks/deliveries/{deliveryId}/attempts.
After you fix the problem, retry the delivery with POST /v1/webhooks/deliveries/{deliveryId}/redeliver. Manual redelivery keeps the delivery identifier and attempt history, resets the attempt counter, and queues the delivery again. While that delivery is in progress, the endpoint returns 404.
Your receiver must still deduplicate on webhook-id. Signed retries keep the same delivery identifier but receive a fresh timestamp and signature for each attempt. See Prevent replay and duplicate processing.
Deployment
Route /v1/webhooks to the webhooks service. To deploy the webhooks service yourself, see Webhooks service.
Configure signing on the webhooks service itself using the variables in Webhook signing configuration.
Updated 3 days ago