Webhooks

Annature uses webhooks to notify your application in real time when specific events occur — such as an envelope being completed, a recipient viewing or declining to sign, or a token-based session being requested. These events are sent as HTTP POST requests to one or more webhook endpoints that you register with your organisation.

Webhooks allow your system to respond programmatically to key actions without polling for changes. For example, you might update the status of a deal in your CRM when a contract is signed, or trigger an internal alert if a recipient declines to sign

All webhook requests are sent in JSON format and include a signature in the request header that allows you to verify the event was sent by Annature.

​

Delivery behaviour

Webhook events are delivered to your endpoint using an HTTP POST request. Each event is attempted once initially. If your endpoint does not return a 2xx response, Annature will retry the request once per hour for up to 72 hours.

After three days of failed delivery attempts, the endpoint will be automatically disabled and the account owner will be notified via email.

You can monitor and troubleshoot webhook failures from the Developers section of the Annature dashboard.

Important: Your endpoint must return a 2xx status code as quickly as possible to confirm successful receipt. Do not wait to complete internal processing before responding.

​

Multiple endpoints

You can register up to 100 unique webhook endpoints for your organisation. This allows you to support multiple environments — such as staging and production — using the same Annature account.

Each registered endpoint will receive all webhook events triggered by your organisation. Your application should gracefully ignore any events that are not relevant — for example, an envelope ID that only exists in another environment.

​

Signature verification

To ensure that incoming requests are genuinely from Annature, each webhook request includes an X-Annature-Signature HTTP header. This signature can be used to validate the payload using your endpoint’s secret key.

Your signing secret is available in the Developers section of the dashboard. If the signature does not match, you should reject the request with an appropriate error code.

{
  "X-Annature-Signature": "da6d893b3e5b4b0592cf45432e256e85"
}

Signature verification is optional but highly recommended for production deployments.

​

Responding to events

To acknowledge successful receipt of a webhook, your endpoint must return any 2xx HTTP status code. All other codes — including 3xx, 4xx, and 5xx — are treated as failures and will trigger retries.

Annature enforces a 10 second timeout for webhook requests. If your server does not respond within this window, the attempt is considered a failure — even if it eventually returns a 2xx status code.

To acknowledge successful receipt of a webhook, your endpoint must return any 2xx HTTP status code. All other codes — including 3xx, 4xx, and 5xx — are treated as failures and will trigger retries.

Avoid any lengthy processing or logic before responding. The ideal implementation:

• Validate the signature (if enabled)
• Store the payload or enqueue for later processing
• Return a 200 OK immediately