Webhooks

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. You can register different webhook endpoints for test or live events and select the specific events to subscribe to for each endpoint.

​

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, SignatureAPI delivers events for all envelopes, whether in test or live 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.

​

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.

​

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(signing_secret);
wh.verify(webhook_payload, webhook_headers);

Libraries are available for the following languages: JavaScript and TypeScript, Python, Java and Kotlin, Rust, Go, Ruby, PHP, C#, and Elixir.

​

Source IP

If your webhook receiving endpoint is behind a firewall or NAT and you need a list of IP addresses to allow traffic, please contact support.

​

Tools

These tools can be useful for testing webhooks:

• 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.