Fundamentals
Webhooks
Receive SignatureAPI events at your webhook endpoint: set it up per mode, verify signatures on the raw body, handle retries and duplicate deliveries.
Use webhooks to receive real-time events from your SignatureAPI account, so your backend can respond to these events and act accordingly.
Receiving webhook events is useful for handling asynchronous events such as when a recipient signs an envelope, an envelope is completed, a deliverable is generated, or an email to a recipient bounces.
Setting Up Webhooks
You can receive events by registering a webhook endpoint in the Dashboard. Select the specific events to subscribe to for each endpoint.
Test and live endpoints
Each webhook endpoint belongs to one mode. An endpoint you create with Test Mode on receives events from test envelopes only, and an endpoint created with Test Mode off receives events from live envelopes only. To receive both, register an endpoint in each mode.
Events
When an event happens, SignatureAPI creates a new Event object.
This is an example of an event object for a recipient.completed event:
{
"id": "evt_4p2oouvNvjp1I9ckgqycH2",
"type": "recipient.completed",
"timestamp": "2025-12-31T15:00:01.999Z",
"data": {
"envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
"envelope_metadata": {
"customer_ref": "x9550501",
"account_annual_revenue": "$4,500,000"
},
"object_id": "re_7v7Sion0vqjJioYmwfZ9mf",
"object_type": "recipient",
"recipient_type": "signer"
}
}Learn more about the different types of events.
Topic Filters
By default, an endpoint receives events for every envelope in its mode.
To receive events only for specific envelopes at a webhook endpoint, use topic filters.
When creating an envelope, you can specify up to 10 topics in the topics array of the Envelope object. Then, while setting up a webhook endpoint, list all the topics to receive events for those envelopes.
Event Delivery
SignatureAPI delivers the event via a POST request to your webhook endpoint, with the Event object as the JSON payload.
Delivery is successful if your endpoint responds with a status code in the 2XX range (200 to 299). Any other status code means the delivery failed.
Duplicate deliveries
The same event can reach your endpoint more than once, for example when your endpoint processed it but its response never arrived and the delivery was retried. Make your handler idempotent:
- Read the event
id(evt_...) from the payload. Every delivery of one event carries the sameid. - If you have already processed that
id, respond with200and stop. - Otherwise, process the event, store its
id, and respond with a2XXstatus.
Respond quickly, and move slow work (downloading deliverables, calling other services) to a background job.
Retries
If your endpoint responds with a status code outside the 2XX range, SignatureAPI will keep trying to deliver the event for up to 48 hours, using an exponential backoff strategy.
A delivery goes like this:
- SignatureAPI sends the event to your endpoint in a
POSTrequest. - A
2XXresponse ends the delivery. - Any other response, or no response, schedules a retry. The wait between attempts grows with each failure.
- 48 hours after the event, SignatureAPI stops retrying it.
Authentication
Webhook notifications are secured with an HMAC signature included in the webhook-signature header, following the Standard Webhooks specification.
You can find the Signing Secret in the right column of the webhook endpoint definition:
Standard Webhooks provides SDKs to simplify webhook verification. For example, to verify signatures in JavaScript or TypeScript:
import { Webhook } from "standardwebhooks";
const wh = new Webhook(signingSecret);
// rawBody: the request body exactly as received, before any JSON parsing.
// headers: the request headers, including webhook-id, webhook-timestamp and webhook-signature.
const event = wh.verify(rawBody, headers); // throws if the signature does not matchLibraries are available for the following languages: JavaScript and TypeScript, Python, Java and Kotlin, Rust, Go, Ruby, PHP, C#, and Elixir.
Two details make verification fail when they are missed:
- Verify the raw body. The signature covers the exact bytes SignatureAPI sent. If your framework parses the JSON first, re-serializing it changes spacing or key order and the check fails. In Express, for example, read the webhook route with
express.raw({ type: "application/json" }). - Pass all three headers. The signature is computed over
webhook-id,webhook-timestamp, and the body, and sent inwebhook-signature. The libraries also reject awebhook-timestampmore than 5 minutes from your server’s clock, so keep the clock in sync.
To debug a failing check, paste a delivery with its headers and your signing secret. The check runs in your browser:
Webhook signature verifier
Paste a delivery and your endpoint's signing secret. Everything runs in your browser; nothing is sent or stored.
Show the steps
See a worked example
A sample envelope.completed webhook signed with a sample secret that exists only for this example. Every step passes.
Pass The signature matches: the webhook is authentic.
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1793632900
webhook-signature: v1,gnEiAfsZL9JiA8cyOxq+XOiA5sHN5cR26xykSizyz4Q=
{"id":"evt_4GpGD1cNnrkemsTLAvPW9G","type":"envelope.completed","timestamp":"2026-11-02T15:21:40.000Z","data":{"object_id":"eb4cf433-a8af-4161-b37b-7ef57d423e56","object_type":"envelope","envelope_id":"eb4cf433-a8af-4161-b37b-7ef57d423e56","envelope_metadata":{"customer_ref":"x9550501"}}} whsec_ZG9jcy1zYW1wbGUtc2lnbmluZy1zZWNyZXQtMDAwMQ== - Pass
Read the headers
Found all three signature headers.
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W webhook-timestamp: 1793632900 webhook-signature: v1,gnEiAfsZL9JiA8cyOxq+XOiA5sHN5cR26xykSizyz4Q=
- Pass
Check the timestamp
Sent at 2026-11-02T15:21:40.000Z, within 5 minutes of your clock.
- Pass
Build the signed content
The
webhook-idvalue, a dot, thewebhook-timestampvalue, a dot, then the raw body.msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1793632900.{"id":"evt_4GpGD1cNnrkemsTLAvPW9G","type":"envelope.completed","timestamp":"2... (331 characters) - Pass
Decode the signing secret
Removed the
whsec_prefix and base64-decoded the rest into a 31-byte key. - Pass
Compute the expected signature
HMAC-SHA256 of the signed content with that key, base64-encoded and prefixed with v1 and a comma.
v1,gnEiAfsZL9JiA8cyOxq+XOiA5sHN5cR26xykSizyz4Q=
- Pass
Compare signatures
The signature in
webhook-signaturematches. The webhook is authentic.
Source IPs
If your webhook endpoint is behind a firewall, allow traffic from the following IP addresses:
44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/56Tools
These tools can be useful for testing webhooks:
- SignatureAPI CLI:
npx signatureapi listendelivers test-mode events to a handler on your machine and saves the endpoint’s signing secret into your.envfile. - Webhook.site: Generates a random endpoint URL and lets you inspect POST requests sent to that endpoint.
- ngrok: Sets up a tunnel from an internet-facing endpoint to your local machine, allowing you to process webhooks locally.