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.
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
- Go to Settings → Webhooks.
- In the io.sign section, select New webhook.
- 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.
- Choose the Vault scope: All vaults, or one vault.
- 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.
- Select Create webhook.
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
| Group | Events |
|---|---|
| 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 & signers | vault.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.
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 status | API status | Meaning |
|---|---|---|
| Queued | pending | The delivery is waiting to be sent. |
| Sending | in_flight | An attempt is in progress. |
| Delivered | succeeded | Your endpoint responded with a 2xx status. |
| Retrying | failed | An attempt failed, and we retry it automatically. |
| Failed | dead | Every 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.
Updated 3 days ago