Webhooks in the dashboard

Add, edit, and monitor io.sign webhooks from the io.finnet dashboard

io.sign webhooks send an HTTPS POST to a URL you control when something happens in your organisation, such as a signature completing or a reshare starting. On io.finnet-managed deployments, you can manage them in the io.finnet dashboard under Settings → Webhooks, in the io.sign section, without calling the API.

The Webhooks settings page with one active webhook in each section: an io.sign webhook, https://webhooks.example.com/io-sign, sending 1 event for one vault, and an io.vault webhook, https://webhooks.example.com/io-vault, sending 7 events for all vaults
📨

Who can use this page. You need the Admin or Admin Compliance role, access to vaults, and New Experience turned on in the dashboard. The io.sign section appears only when io.sign webhooks are available in your environment. To manage subscriptions through the API instead, or on a self-hosted io.sign deployment, see Webhooks.

Add a webhook

  1. Go to Settings → Webhooks.
  2. In the io.sign section, select New webhook.
  3. Enter the Endpoint URL. It must be an HTTPS URL on a public address, with no credentials in it, and no longer than 2,048 characters.
  4. Choose the Vault scope: All vaults, or one vault.
  5. Choose the events to send. Turn on All events to send every io.sign event, including event types we add later. Otherwise, tick the events to send. Tick a group to select every event in it.
  6. Select Create webhook.
The New webhook form for io.sign with an endpoint URL, All vaults scope, and the Signatures group expanded with all eight events ticked

A webhook scoped to one vault receives that vault's signature, reshare, and vault events. signer.created isn't tied to a vault, so only an All vaults webhook receives it. When you choose one vault, the form removes signer.created from the selected events.

Events

GroupEvents
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
Vaults & signersvault.created, vault.activated, vault.archived, vault.unarchived, vault.deleted, signer.created (All vaults only)

Manage a webhook

Select a webhook in the list to open it. The webhook page shows its status, its details, its signing secret, and its deliveries.

An active io.sign webhook page with Edit, Pause, and Delete actions, its details including the vault scope, and the masked signing secret with Rotate secret and Reveal

From the webhook page you can:

  • Edit the URL, vault scope, or events. Saving doesn't change the signing secret.
  • Pause the webhook to stop sending new events to it while keeping its settings. Select Resume to start sending again.
  • Delete the webhook. Deleting can't be undone. Deliveries already queued are still sent.

If a webhook receives event types the dashboard doesn't list, for example because you created it through the API, editing keeps them unless you change its events or vault scope. Saving those changes removes them.

While a webhook is paused, we don't send events that happen in the meantime, and we don't send them later when you resume it. Deliveries that were already queued are still sent and retried, and a redelivery is still sent.

A webhook shows Disabled when someone in your organisation disabled it through the API. Select Enable to turn it back on. A failing endpoint never disables a webhook on its own.

The dashboard asks you to confirm your identity again before a sensitive change: creating a webhook, changing its URL, vault scope, or events, pausing or deleting it, and revealing or rotating its signing secret.

Signing secret

Each webhook has its own signing secret, which your server uses to check that a delivery came from io.finnet and wasn't changed on the way. Select Reveal to show the secret, which starts with whsec_, then Copy secret and store it in your server's secret store. If the panel says signing isn't enabled for this deployment, deliveries are unsigned. Your server can't confirm that an unsigned delivery came from io.finnet. Don't accept unsigned deliveries in production. Contact [email protected] to have signing enabled.

Select Rotate secret to issue a new secret. Until the time shown in Signs until, under Previous secret, deliveries are signed with both the new and the old secret, so you can deploy the new secret without dropping a delivery. The overlap is 24 hours by default, and you can't rotate again until it ends.

To check signatures on your server, follow the Node.js verification example.

Deliveries

The Deliveries table lists the events sent to the webhook, with the status of each:

Dashboard statusAPI statusMeaning
QueuedpendingThe delivery is waiting to be sent.
Sendingin_flightAn attempt is in progress.
DeliveredsucceededYour endpoint responded with a 2xx status.
RetryingfailedAn attempt failed, and we retry it automatically.
FaileddeadEvery attempt failed, and we stopped retrying.

Select a delivery to see each attempt, the response your endpoint returned, and the exact payload we sent. Select Redeliver to send a Delivered, Retrying, or Failed delivery again as a new round of attempts, for example after your endpoint was down. Retrying and Failed deliveries also have Redeliver in their table row. A redelivery goes to the URL the delivery was first sent to, even if you've changed the webhook's URL since.

A redelivery keeps the same webhook-id, so a receiver that deduplicates on webhook-id skips it while it still holds that ID. If your receiver no longer holds the ID, for example because it's older than your retention period, it processes the event again. See Prevent replay and duplicate processing.

For how many times we retry and how long we wait between attempts, see Delivery retries.


Did this page help you?