Skip to main content
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.
Set up your webhook in the Dashboard

​
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

If you want to use this feature, please contact support at support@signatureapi.com
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.
SignatureAPI does not guarantee the order of event delivery, so your endpoint should be able to handle events arriving out of order.

​
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.
If delivery fails consistently for several days, we will notify the account owner and may temporarily disable deliveries to the 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:
Find your webhook's signing secret
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.