Webhooks

Events sent to your server as they happen: what is sent, checking the signature, retries and the delivery log.

A webhook sends an event to your server when something happens in a workspace: an envelope is sent or completed, someone signs, time off is booked or approved. Someone who may manage webhooks in the workspace subscribes in the app (Settings › API, under Webhooks) or through the API with the webhooks:manage scope:

POST /v1/workspaces/{workspace_id}/webhooks
Idempotency-Key: 6f1c…

{ "url": "https://hooks.example.com/esign", "events": ["envelope.completed", "timeoff.approved"] }

The answer holds the signing secret (whsec_…). It is shown this once; keep it with your other secrets. We keep it encrypted, under a key of its own that only our key service can unlock.

What is sent

Each delivery is a POST of JSON:

{
  "id": "evt_01a16d3fd3507be78e41c4540aa20a3c",
  "type": "envelope.completed",
  "created_at": "2026-10-24T09:30:00Z",
  "workspace_id": "wsp_…",
  "data": {
    "envelope": {
      "id": "env_…",
      "external_id": "JIRA-101",
      "reference": "DOC-0051",
      "status": "completed",
      "created_at": "2026-10-23T14:02:00Z",
      "sent_at": "2026-10-23T14:05:00Z",
      "completed_at": "2026-10-24T09:30:00Z",
      "recipients": [{ "id": "rcp_…", "role": "signer", "status": "signed", "routing_order": 1 }]
    }
  }
}

A payload always holds IDs, states, times and your external_id (the reference you gave the envelope with POST or PATCH /envelopes). Names and details come only when the webhook was made with the read scope for them: with documents:envelopes:read, an envelope's title, its reference_values and each recipient's name; with people:read, a time off request's person_name. In the app, that is Include names and reference values. They are read as the person who made the webhook sees them, so an envelope they can't see carries none. A sensitive detail, a document's contents and anything about sickness are never sent.

The events are envelope.created, envelope.submitted, envelope.sent, envelope.completed, envelope.voided and envelope.expired; approval.approved, approval.changes_requested and approval.rejected; recipient.viewed, recipient.signed and recipient.declined; and timeoff.requested, timeoff.approved, timeoff.declined and timeoff.cancelled. Envelope events can be limited to some document types with document_type_ids.

Checking the signature

Every delivery carries X-Signature-Timestamp (seconds) and X-Signature. Work out HMAC-SHA256 of the timestamp, a full stop and the body exactly as received, using your secret, and compare it with a v1= value in X-Signature. Reject anything whose timestamp is more than five minutes old.

While a secret is being rotated (POST …/webhooks/{id}/rotate-secret), deliveries are signed with both the new and the old secret for 24 hours, so X-Signature holds two v1= values. Change over to the new secret within the day.

Retries and duplicates

Answer with any 2xx within ten seconds. Anything else is tried again later, for 24 hours, at growing intervals. A 4xx other than 408 or 429 is not retried. An event can arrive more than once: use its id (also in X-Webhook-Id) to do the work once.

After 24 hours without a delivery the webhook is marked failing, and the company's administrators and the person who made it are emailed. It comes back to active with the next delivery that goes through, and they are emailed again to say so. A single failed delivery emails nobody.

The delivery log

GET …/webhooks/{id}/deliveries lists each delivery with its outcome and your server's answer. POST …/deliveries/{delivery_id}/redeliver sends one again.

Webhooks go only to https addresses on the public internet; redirects are not followed.

Catching up

If your server was down, read what you missed instead of waiting for retries: GET /v1/workspaces/{workspace_id}/events?after={the last evt_ you handled} returns the events of the last 30 days in order, with the same bodies deliveries carry, whether or not a webhook subscribes to them. Page on with next_cursor; types narrows the list.

On this page