Administrators

Webhooks

With a webhook, bb-sign notifies your systems the moment something happens to an envelope: when it is sent, when a signer signs or when it is completed. Every notification arrives signed, so your system can confirm it comes from bb-sign. This page explains how to set it up and monitor it; the code that verifies the signature is in Webhooks for developers.

Who: organization admins and platform admins. Where: Settings, Webhooks tab.

Create a webhook

Press New webhook.
Enter the Endpoint URL. It must use HTTPS and be reachable from the internet; bb-sign checks this at creation and on every delivery.
Tick the Events to receive, at least one.
Press New webhook. The Save this signing secret now dialog shows the Signing secret. Store it in your organization’s secret manager: it is shown once and your system needs it to verify every delivery.

Event	Name in the app	When it is sent
`envelope.sent`	Envelope sent	The envelope was sent to its signers.
`envelope.completed`	Envelope completed	Every signer signed.
`envelope.cancelled`	Envelope cancelled	The envelope was cancelled.
`envelope.expired`	Envelope expired	The envelope expired before completion.
`signer.signed`	Signer signed	One signer signed; others may still be pending.
`signer.viewed`	Signer opened the document	A signer opened the document.

Your organization can hold up to 20 webhooks.

Test a webhook

Send test delivers a sample event, signed like a real one, and shows your endpoint’s answer. Use it to confirm the setup before you rely on the webhook.

Enable and disable

Disable pauses deliveries without deleting the configuration; Enable resumes them. Events that happen while the webhook is disabled are recorded in the history as Not sent, and once it is enabled again bb-sign continues with new events.

Rotate the secret

Rotate secret generates a new signing secret without interrupting deliveries. For 24 hours, every delivery carries a signature with the previous secret and one with the new secret, so you can update your system without a maintenance window.

Delete a webhook

Delete stops deliveries and deletes the webhook’s delivery history. Deletion is permanent.

Retries and automatic disabling

If your endpoint does not confirm a delivery with a 2xx answer, bb-sign retries it after waits of 1m, 5m, 30m, 2h, 12h, with a random variation of 20 %: about 15 hours in all. The delivery content is the same on every retry.

After 3 consecutive deliveries that fail after all their retries, bb-sign disables the webhook to protect your endpoint. The row shows Disabled automatically and the organization’s admins receive an email with the subject “Action required: bb-sign disabled a webhook endpoint”. bb-sign probes the endpoint again every 6 hours and re-enables it as soon as it answers correctly.

Review the delivery history

History opens the webhook’s delivery list. Each row shows the status, the event, the date and the number of attempts. Opening a delivery shows every attempt with its outcome, response code, duration and, if a retry is scheduled, the time of the next attempt.

Status	Meaning
Preparing	bb-sign is preparing the delivery.
Sending	An attempt is in progress or scheduled.
Delivered	Your endpoint confirmed the delivery.
Gave up	Every retry completed without confirmation. Check your endpoint.
Not sent	The webhook was disabled when the event happened.
Could not be built	A problem occurred while preparing the delivery. Report it to Binary Bridges support.

Attempt outcome	Meaning
Accepted	Your endpoint answered 2xx.
Rejected	Your endpoint answered with another code, shown beside it.
Unreachable	No answer, due to a DNS, connection or timeout problem.

The history is kept for 90 days. Creating a webhook, rotating its secret and deleting it are recorded in the audit trail.

Webhooks for developersThe content of each delivery, its headers and the code that verifies the signature in JavaScript and Java.