Skip to content

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.

New Endpoint form in the Dashboard webhook settings, with fields for the endpoint URL, a description, the events to subscribe to, and topics
Settings > Webhooks > Endpoints > New 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:

JSON
{
  "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.

SignatureAPI does not guarantee the order of event delivery, so your endpoint should be able to handle events arriving out of order.

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:

  1. Read the event id (evt_...) from the payload. Every delivery of one event carries the same id.
  2. If you have already processed that id, respond with 200 and stop.
  3. Otherwise, process the event, store its id, and respond with a 2XX status.

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:

  1. SignatureAPI sends the event to your endpoint in a POST request.
  2. A 2XX response ends the delivery.
  3. Any other response, or no response, schedules a retry. The wait between attempts grows with each failure.
  4. 48 hours after the event, SignatureAPI stops retrying it.
Each event is retried for up to 48 hours. If your endpoint is down longer, events older than 48 hours at recovery are not redelivered; fetch them from the events endpoint.

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:

Webhook endpoint details in the Dashboard, with the hidden Signing Secret and the eye icon that reveals it, below the topics and subscribed events
Settings > Webhooks > your endpoint

Standard Webhooks provides SDKs to simplify webhook verification. For example, to verify signatures in JavaScript or TypeScript:

JavaScript
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 match

Libraries 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 in webhook-signature. The libraries also reject a webhook-timestamp more 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.

Webhook request and secret
The headers, a blank line, then the raw body exactly as received. A request line such as POST /webhooks HTTP/1.1 is ignored.
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.

Sample request
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"}}}
Sample signing secret
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-id value, a dot, the webhook-timestamp value, 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-signature matches. 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::/56

Tools

These tools can be useful for testing webhooks:

  • SignatureAPI CLI: npx signatureapi listen delivers test-mode events to a handler on your machine and saves the endpoint’s signing secret into your .env file.
  • 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.