---
title: "Webhooks"
description: "Receive SignatureAPI events at your webhook endpoint: set it up per mode, verify signatures on the raw body, handle retries and duplicate deliveries."
canonical: "https://signatureapi.com/docs/api/webhooks"
source: "https://signatureapi.com/docs/api/webhooks.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:41:33Z"
---

# Webhooks

Receive SignatureAPI events at your webhook endpoint: set it up per mode, verify signatures on the raw body, handle retries and duplicate deliveries.

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/resources/events/recipient-events#recipientcompleted), an [envelope is completed](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted), a [deliverable is generated](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), or an [email to a recipient bounces](https://signatureapi.com/docs/api/resources/events/recipient-events#recipientsoft_bounced).

## Setting Up Webhooks

You can receive events by registering a webhook endpoint in the [Dashboard](https://dashboard.signatureapi.com/settings/webhooks). Select the [specific events](https://signatureapi.com/docs/api/resources/events/envelope-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](https://signatureapi.com/docs/images/create-webhook-screen.webp)

*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](https://signatureapi.com/docs/api/test-mode) 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](https://signatureapi.com/docs/api/resources/events/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](https://signatureapi.com/docs/api/resources/events/envelope-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](https://signatureapi.com/docs/api/resources/envelopes/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](https://signatureapi.com/docs/api/resources/events/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.

> **Note:** 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.

> **Warning:** 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](https://signatureapi.com/docs/api/resources/events/all).

## Authentication

Webhook notifications are secured with an HMAC signature included in the `webhook-signature` header, following the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity).

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](https://signatureapi.com/docs/images/webhook-signing-secret.webp)

*Settings > Webhooks > your endpoint*

Standard Webhooks provides SDKs to simplify webhook verification. For example, to verify signatures in [JavaScript or TypeScript](https://www.npmjs.com/package/standardwebhooks):

```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](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/javascript), [Python](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/python), [Java and Kotlin](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/java), [Rust](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/rust),
[Go](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/go), [Ruby](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/ruby), [PHP](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/php), [C#](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/csharp), and [Elixir](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/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:

Interactive tool: verify a webhook signature in the browser on [this page](https://signatureapi.com/docs/api/webhooks). Nothing is sent anywhere.

To verify a webhook (Standard Webhooks):
1. Read the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers.
2. Reject the request if `webhook-timestamp` (Unix seconds) is more than 5 minutes from your clock.
3. Build the signed content: `<webhook-id>.<webhook-timestamp>.<raw body>`. Use the raw body exactly as received.
4. Remove the `whsec_` prefix from the signing secret and base64-decode the rest to get the key.
5. Compute HMAC-SHA256 of the signed content with that key, base64-encode it and prefix it with `v1,`.
6. Compare it, in constant time, with each space-separated entry of `webhook-signature`. One match means the webhook is authentic.

Example signed content for a `envelope.completed` event:

```text
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1793632900.{"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"}}}
```

## Source IPs

If your webhook endpoint is behind a firewall, allow traffic from the following IP addresses:

```text
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](https://signatureapi.com/docs/cli/webhooks): `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](https://webhook.site): Generates a random endpoint URL and lets you inspect POST requests sent to that endpoint.
- [ngrok](https://ngrok.com/): Sets up a tunnel from an internet-facing endpoint to your local machine, allowing you to process webhooks locally.
