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

ActionEndpoint
Create a subscriptionPOST /v1/webhooks
List subscriptionsGET /v1/webhooks
Get a subscriptionGET /v1/webhooks/{id}
Change its url, events, vaultId, or statusPATCH /v1/webhooks/{id}
Delete a subscriptionDELETE /v1/webhooks/{id}

A subscription belongs to an organisation and specifies its events and destination URL:

  • url must use HTTPS, be at most 2,048 characters, contain no credentials, and not point to a private or reserved address.
  • events lists at least one event type.
  • vaultId restricts signature, reshare, and vault events to one vault. Leave it out for organisation-wide delivery, or set it to null in a PATCH to widen an existing subscription. signer.created is organisation-wide only, so a subscription with a vaultId never receives it.
  • status is active, paused, or disabled. Only active subscriptions receive new deliveries.

Supported events

Event familySupported event types
Signaturessignature.created, signature.presigning, signature.signing, signature.completed, signature.rejected, signature.failed, signature.expired, signature.cancelled
Resharesreshare.created, reshare.presigning, reshare.signing, reshare.completed, reshare.rejected, reshare.failed, reshare.expired, reshare.cancelled
Vaultsvault.created, vault.activated, vault.archived, vault.unarchived, vault.deleted
Signerssigner.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.

VariableDefaultBehaviour
WEBHOOKS_MAX_ATTEMPTS6Total attempt budget, including the initial attempt. Set to 1 to disable automatic retries after a failed attempt.
WEBHOOKS_BACKOFF_SECONDS10,30,120,600,3600Comma-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_MS10000Timeout for an HTTP delivery attempt, in milliseconds.
WEBHOOKS_POLL_INTERVAL_MS1000Delay between worker polls when the previous batch wasn't full, in milliseconds.
WEBHOOKS_BATCH_SIZE25Maximum deliveries claimed and processed concurrently in one batch per worker.
WEBHOOKS_LEASE_TTL_MS60000Time 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=10000

These 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.


Did this page help you?