Webhooks

Optional. Without webhooks, integrators get email notifications and can poll the API. With one, we POST events to your endpoint with HMAC-signed bodies and retry on failure.

Registering a webhook

Hooks are per workspace. An API key belongs to exactly one workspace, so "a webhook per API key with a stable secret" is the same thing as a workspace hook: register it once, keep its secret, and every document the workspace sends — over the API or from the dashboard — reaches it. Three ways to register:

1. Over the API — POST /v1/hooks, for integrators and for connectors such as Zapier and Make. The secret comes back once, as secret in the create response; lost it, or rotating on a schedule? POST /v1/hooks/{id}/rotate mints a new one and keeps the old one valid for 24 hours. Posting the same target_url again replaces the hook. "payload": "minimal" gives bodies without personal data. See Managing hooks over the API below.
2. Workspace-wide, from the dashboard — at Developers → Webhooks. Pick the events (or all). The signing secret is shown once on creation; the dashboard keeps only its whsec_… prefix afterwards.
3. Per document — pass callback_url on POST /v1/signing-requests. Scoped to that document only; a workspace hook still fires alongside it. The secret comes back once in the response under callback.secret; store it before discarding the response. It gets the full body.

All three register a row in the same webhooks table and share the delivery, signing and retry mechanism documented here. Every delivery is signed with that row's own secret. Each hook also has a payload mode: the full body (the default) or a minimal body without personal data.

Events

"base" is the shared signer-event payload described in Signer events. Every payload carries document_id, which is how a document-scoped callback_url hook matches the template_instance.* and signer events too — and with it metadata, the object you passed when you created the document through the API (see below).

Every signing_request.* event also carries role and reference at the top level (since the 2026-10-02 release, webhook-top-level-role-reference), so a receiver can correlate without reading the signer block: role is the role you sent for the signer on POST /v1/signing-requests, else, for a template recipient, the template slot's role label (null when there is neither); reference is your per-signer reference (null when none). document.completed and template_instance.* do not carry them.

Which hooks receive new events

A hook whose events list is empty receives every event type — including types added later, such as the six signer events of the 2026-09-24 release. Every callback_url hook is such a hook. A hook with an explicit list receives exactly that list. So:

• Answer 2xx to event types you do not handle, ping included. An unanswered or non-2xx delivery is retried for about 45 hours (see Retries) before it gives up.
• Branch on event, never on the shape of the body.

Signer events

signing_request.viewed, .declined, .withdrawn, .sms_sent, .sms_failed and .sms_verified share one base, after the envelope and metadata:

{
  "event":              "signing_request.sms_failed",
  "event_id":           "evt_8c1d…",
  "created_at":         "2026-09-24T09:14:03.120Z",
  "workspace_id":       "3c1f…",
  "metadata":           { "mandate": "M-2026-0415" },
  "signing_request_id": "11111111-…",
  "document_id":        "8a1e4f9a-…",
  "signer":             { "email": "anna@example.ch", "name": "Anna Muster", "role": null, "slot": 1, "reference": "person-8812", "company": "Muster AG", "job_title": "Geschäftsführerin" },
  "occurred_at":        "2026-09-24T09:14:02.981Z",
  "role":               "Client",
  "reference":          "person-8812",
  "reason":             "landline",
  "phone_masked":       "•••• •••• 2233",
  "sms_allowance":      { "monthly": 300, "used": 41, "remaining": 259, "resets_at": "2026-10-01T00:00:00.000Z" }
}

(Anna is a template recipient here: signer.role is null, and the top-level role is her template slot's label.)

signing_request.signed, signing_request.expired and document.completed carry the same signer block (without occurred_at). If the signer row cannot be read at that moment, the block of signed and completed still carries email and name, with null for the rest, rather than holding the event back. Before the 2026-10-02 release signing_request.expired carried only { email, name }.

The other five differ only in event and the fields after occurred_at:

// signing_request.viewed — nothing after occurred_at

// signing_request.declined
"reason": "Das Geburtsdatum ist falsch."          // or null

// signing_request.withdrawn
"withdrawn_by": "api"                             // or "sender"

// signing_request.sms_sent
"phone_masked": "•••• •••• 2233",
"attempt": 2,                                     // the second code for this request
"sms_allowance": { "monthly": 300, "used": 42, "remaining": 258, "resets_at": "2026-10-01T00:00:00.000Z" }

// signing_request.sms_verified
"phone_masked": "•••• •••• 2233",
"sms_verified_at": "2026-09-24T09:15:40.112Z"

What each adds and when it fires:

sms_failed.reason:

A wrong code emits nothing (it is on the audit trail), and a phone change with PATCH /v1/signing-requests/{id} emits nothing either — the next sms_sent carries the new phone_masked. The whole SMS flow is on SMS verification.

Document and template payloads

The bodies below show the envelope and every field the event carries. The metadata echo is shown after the envelope for readability; key order is not part of the contract.

signing_request.sent from POST /v1/signing-requests. name is the name you sent (null when you sent only first_name and last_name; the later events carry the stored name); role is the signer's anchor role; slot is the stored signing order, null in a parallel send:

{
  "event":              "signing_request.sent",
  "event_id":           "evt_5b0e…",
  "created_at":         "2026-09-24T09:00:01.412Z",
  "workspace_id":       "3c1f…",
  "metadata":           { "case_id": "ZT-2026-0142" },
  "signing_request_id": "11111111-…",
  "document_id":        "8a1e4f9a-…",
  "signer":             { "email": "tenant@example.com", "name": "Ann Tenant", "role": "tenant", "slot": null, "reference": "crm-contact-4711", "company": null, "job_title": null },
  "locale":             "en",
  "source":             "v1_api"
}

From a direct instantiate the same event also names the template, and role is the slot's role label from the template (null if the slot has none):

  "signer":           { "email": "anna@example.ch", "name": "Anna Muster", "role": "Client", "slot": 1, "reference": "person-8812", "company": "Muster AG", "job_title": "Geschäftsführerin" },
  "locale":           "de",
  "template_id":      "c0ffee00-…",
  "template_version": 4,
  "source":           "v1_api"

From a confirm it carries "source": "template_instance" and no template_id — read that from template_instance.confirmed, which fires just before it.

From a sequential release it carries "source": "sequential_release", the moment of the release as occurred_at, and emailed — see Following a sequential send.

template_instance.staged, an e-sign instance (instantiate with review: true):

{
  "event":             "template_instance.staged",
  "event_id":          "evt_9d21…",
  "created_at":        "2026-09-24T09:00:02.030Z",
  "workspace_id":      "3c1f…",
  "metadata":          { "case_id": "ZT-2026-0142" },
  "document_id":       "8a1e4f9a-…",
  "template_id":       "c0ffee00-…",
  "template_version":  4,
  "kind":              "esign",
  "review_url":        "https://www.wesign.now/en/documents/8a1e4f9a-…/review",
  "review_expires_at": "2026-10-08T09:00:01.977Z",
  "signing_mode":      "sequential",
  "recipients": [
    { "signing_request_id": "11111111-…", "slot": 1, "email": "anna@example.ch" },
    { "signing_request_id": "22222222-…", "slot": 2, "email": "partner@example.ch" }
  ],
  "source":            "v1_api",
  "api_key_id":        "0b9a7e3c-…"
}

A file-only instance (generate with review: true) has "kind": "file" and a filename instead of signing_mode and recipients.

template_instance.confirmed, e-sign. recipients[].status is pending for the recipients invited now and queued for the later ones of a sequential send; expires_at is the signing links' new expiry, counted from the confirm:

{
  "event":            "template_instance.confirmed",
  "event_id":         "evt_1f7a…",
  "created_at":       "2026-09-25T13:12:44.508Z",
  "workspace_id":     "3c1f…",
  "metadata":         { "case_id": "ZT-2026-0142" },
  "document_id":      "8a1e4f9a-…",
  "template_id":      "c0ffee00-…",
  "template_version": 4,
  "kind":             "esign",
  "actor":            "api_key",
  "expires_at":       "2026-10-09T13:12:43.901Z",
  "recipients": [
    { "signing_request_id": "11111111-…", "slot": 1, "email": "anna@example.ch", "status": "pending" },
    { "signing_request_id": "22222222-…", "slot": 2, "email": "partner@example.ch", "status": "queued" }
  ]
}

A file-only confirm carries document_id, template_id, template_version, "kind": "file" and actor — no expires_at, no recipients.

template_instance.discarded:

{
  "event":        "template_instance.discarded",
  "event_id":     "evt_77c0…",
  "created_at":   "2026-10-08T10:00:03.114Z",
  "workspace_id": "3c1f…",
  "metadata":     { "case_id": "ZT-2026-0142" },
  "document_id":  "8a1e4f9a-…",
  "template_id":  "c0ffee00-…",
  "kind":         "esign",
  "reason":       "expired",
  "actor":        "system"
}

A file-only instance is deleted when it is discarded, before the event is sent, so its discarded event carries "metadata": null — match it on document_id, which the staged event gave you together with your metadata.

Following a sequential send

In a sequential send only the first signer is invited at once; the others stay queued and emit nothing. When a signer signs, the next one is promoted to pending — their link works from that moment — and the release emits a signing_request.sent for them:

{
  "event":              "signing_request.sent",
  "event_id":           "evt_8d4f…",
  "created_at":         "2026-09-25T09:41:07.512Z",
  "workspace_id":       "3c1f…",
  "metadata":           { "case_id": "ZT-2026-0142" },
  "signing_request_id": "7f2eac45-…",
  "document_id":        "8a1e4f9a-…",
  "signer":             { "email": "ben@example.com", "name": "Ben Beispiel", "role": "Tenant", "slot": 2, "reference": null, "company": null, "job_title": null },
  "occurred_at":        "2026-09-25T09:41:07.498Z",
  "locale":             "de",
  "source":             "sequential_release",
  "emailed":            false
}

• source: "sequential_release" tells it apart from the document's first sent (v1_api or template_instance). A receiver that only records "the document went out" can skip it.
• emailed says whether we emailed the invitation. It is false when the document was created with send_emails: false — we send nothing and you deliver the link — when our email failed, and when the signer's address is on a domain that accepts no email (we do not send what can only bounce, and the document's sender is told); the link works either way.
• The link is the one the create call already gave you for that signer: signing_url from instantiate or a confirm, signingUrl from POST /v1/signing-requests, or signingUrl on GET /v1/signing-requests/{id}. Webhooks never carry signing links — a link is the signer's credential.
• The release happens while the previous signer's signature is sealed, before that signer's signing_request.signed is emitted, so the two can arrive in either order. Match on signing_request_id and signer.slot, never on arrival order.
• An envelope emits one sent per document of the released signer; one email covers all of them.
• signing_request.viewed fires when the released signer opens the document, document.completed when the last one has signed. GET /v1/documents/{id} shows each signer's status: queued → pending → viewed → signed.

send_emails: false is stored on every signer the call creates, so it holds for a signer released days later. For a staged instance, the value its confirm settles on counts (the confirm body may override the instantiate call's). Requests created before the 2026-09-25 release do not carry it: their later signers are still emailed, and their releases emit sent with "emailed": true.

Documents sent from the dashboard

The editor's Send (one file or an envelope, a document made from a template included) emits one signing_request.sent per document, for its first signer, once the invitations went out; not again for the other signers of a parallel send. It has no source; signer carries email, name and slot, the signing order in a sequential send, else null. Before the 2026-10-05 release the editor's Send emitted none. The template quick-send emits one per invited recipient, also without source. A Send Later emits the same events in the same body when it goes out, not when it is scheduled; before the 2026-10-06 release it emitted none. A sequential release emits its sent whatever sent the document. Every other event — viewed, signed, declined, the SMS events, document.completed, expired — fires for a document whatever sent it.

Envelope and sample payload

Every body is a single flat JSON object: four envelope fields (event, event_id, created_at, workspace_id), the event's own fields at the same level, and metadata when the event names a document. Read fields by name; their order is not part of the contract. That is the full body, the default; a hook with payload: "minimal" receives the minimal body instead.

POST https://yourapp.com/wesign/callback
Content-Type: application/json
User-Agent: letssign.now-webhooks/1.0
X-WeSign-Signature:   t=1757404800,v1=9c3b…a2f1
X-WeSign-Event-Id:    evt_3f9c1a7b2d4e4c6f8a1b2c3d4e5f6a7b
X-WeSign-Event:       document.completed
X-LetsSign-Signature: t=1757404800,v1=9c3b…a2f1
X-LetsSign-Event-Id:  evt_3f9c1a7b2d4e4c6f8a1b2c3d4e5f6a7b
X-LetsSign-Event:     document.completed

{
  "event":              "document.completed",
  "event_id":           "evt_3f9c1a7b2d4e4c6f8a1b2c3d4e5f6a7b",
  "created_at":         "2026-09-09T08:00:00.000Z",
  "workspace_id":       "3c1f…",
  "metadata":           { "case_id": "ZT-2026-0142", "client": "zepf" },
  "signing_request_id": "11111111-…",
  "document_id":        "8a1e4f9a-…",
  "signer":             { "email": "owner@example.com", "name": "Olivia Owner", "role": "landlord", "slot": null, "reference": null, "company": "Owner Estates AG", "job_title": "Director" },
  "signed_pdf_url":     "https://api.wesign.now/v1/documents/8a1e4f9a-…/signed",
  "audit_trail_url":    "https://api.wesign.now/v1/documents/8a1e4f9a-…/audit-trail",
  "sha256":             "4f9a…d21c",
  "cert_serial":        "1a2b…",
  "tsa_provider":       "DigiCert",
  "tsa_signed_at":      "2026-09-09T07:59:58Z"
}

signed_pdf_url and audit_trail_url are API URLs on the same host — GET /v1/documents/{id}/signed and GET /v1/documents/{id}/audit-trail for the document in document_id. Fetch either with your workspace's Bearer key, and pin the fetch to api.wesign.now — neither field ever names any other host. Fetch them when the event arrives and keep your own copy: a workspace can have signed PDFs deleted after a set number of days, after which signed_pdf_url answers 410 deleted_by_retention. The whole flow — the hash check, which status codes to retry, retention, and what to do when the event did not come — is in Documents → Retrieve the signed document.

The User-Agent of a full hook is letssign.now-webhooks/1.0, a name from before the September 2026 rename, and will stay so; a minimal hook sends wesign-webhooks/1. Allow-list the one your hook uses if you filter on UA.

metadata: relinking a delivery to your own record

Every event that carries a document_id also carries metadata — the object you passed as metadata when you created the document through the API (POST /v1/signing-requests, POST /v1/templates/{id}/instantiate or /generate with review: true), or null when the document has none, including every document created from the dashboard. Limits and shape are in API overview → Your own reference.

This is how a connector that lost the HTTP response to its create call finds the document again: put your case number in metadata, and the first webhook for the document (signing_request.sent, fired on dispatch — or template_instance.staged for a review: true instance) hands you the document_id next to it.

The key is omitted only when the lookup failed at send time (the event still arrives, without it), on the test ping, which names no document, and on every delivery to a hook with payload: "minimal". A minimal hook therefore relinks by document_id: store it from your create call's response, or read metadata back with GET /v1/documents/{id}.

Payload modes: full and minimal

Each hook has a payload mode, chosen with payload on POST /v1/hooks or switched per hook in the dashboard (the secret stays):

A document-scoped callback_url hook is created with the full body, and the API cannot make it minimal: POST /v1/hooks with the same URL creates a separate workspace hook and leaves the callback_url hook as it is. For identifiers only, register a workspace hook with POST /v1/hooks and "payload": "minimal", and do not pass callback_url.

A minimal body has exactly these keys:

signing_request.signed:

{"event":"signing_request.signed","event_id":"evt_3f9c1a7b2d4e4c6f8a1b2c3d4e5f6a7b","created_at":"2026-10-02T09:14:03.120Z","document_id":"8a1e4f9a-5b6c-4d7e-8f90-a1b2c3d4e5f6","signing_request_id":"11111111-2222-4333-8444-555555555555","role":"tenant","reference":"person-8812"}

document.completed:

{"event":"document.completed","event_id":"evt_9b1d2c3e4f5a6b7c8d9e0f1a2b3c4d5e","created_at":"2026-10-02T09:14:03.410Z","document_id":"8a1e4f9a-5b6c-4d7e-8f90-a1b2c3d4e5f6","signed_pdf_url":"https://api.wesign.now/v1/documents/8a1e4f9a-5b6c-4d7e-8f90-a1b2c3d4e5f6/signed","sha256":"d21c…","audit_trail_url":"https://api.wesign.now/v1/documents/8a1e4f9a-5b6c-4d7e-8f90-a1b2c3d4e5f6/audit-trail"}

signing_request.expired and signing_request.declined have the shape of signed (a decline carries no reason in this mode):

{"event":"signing_request.expired","event_id":"evt_77c0a1b2c3d4e5f6a7b8c9d0e1f2a3b4","created_at":"2026-10-16T10:00:03.114Z","document_id":"8a1e4f9a-5b6c-4d7e-8f90-a1b2c3d4e5f6","signing_request_id":"11111111-2222-4333-8444-555555555555","role":"tenant","reference":"person-8812"}

• document_id is the documentId of the POST /v1/signing-requests response (document_id of instantiate); signing_request_id is that signer's signers[].signingRequestId.
• role and reference are the same top-level values a full body carries (see Events); null when the signer has none.
• sha256 is the lowercase hex SHA-256 of exactly the bytes GET signed_pdf_url serves. The audit trail is a separate PDF at audit_trail_url, rendered on each request, so sha256 does not cover it and its bytes can differ between fetches. It is not the sha256 of GET /v1/documents/{id}, which hashes the file as it was sent for signature — see Check the hash.
• An event emitted while a hook is minimal is stored for it only as the minimal body, so the personal data is not kept on our side for that hook either.
• Switching a hook to minimal applies to its deliveries still being retried too: they are cut down to the minimal body when they are sent. Switching back to full applies to new events only.

Data you need beyond identifiers (a signer's name, metadata) is available with your API key: GET /v1/documents/{id} and GET /v1/signing-requests/{id}.

Verifying a signature

Your endpoint must verify the signature before trusting the body. This is the exact scheme — nothing is left to guess:

Recommended receiver rules:

• Replay tolerance: 300 seconds. Reject a delivery whose t is more than five minutes from your clock. Our retry schedule re-signs every attempt, so a legitimate late delivery never fails this check.
• Idempotency on X-WeSign-Event-Id. Delivery is at-least-once; the id (evt_ + 32 hex) is stable across retries of the same event. Store it and short-circuit repeats after the signature check.
• Compare in constant time, and hash the raw body — a re-serialised JSON object will not match.
• Try every v1= entry. Split the header on ,, take t from the first part and compare your HMAC against each v1= part. A receiver that only reads the first entry still holds the old secret during a rotation window while the first entry is signed with the new one — if yours is written that way, switch to the new secret immediately after rotating.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyWeSignSignature(
  rawBody: string | Buffer,
  header: string | null | undefined,
  secret: string,
  toleranceSec = 300,
): boolean {
  if (!header) return false
  // t=<t>,v1=<hex>[,v1=<hex>] — two entries for 24 h after a secret rotation.
  const parts = header.split(',')
  const t = parts[0]?.startsWith('t=') ? parts[0].slice(2) : null
  if (!t || !/^\d+$/.test(t)) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false
  const body = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8')
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')
  const b = Buffer.from(expected, 'hex')
  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const a = Buffer.from(p.slice(3), 'hex')
      return a.length === b.length && timingSafeEqual(a, b)
    })
}

// Express: keep the raw bytes on this one route.
import express from 'express'
const app = express()
app.post('/wesign/callback', express.raw({ type: 'application/json' }), async (req, res) => {
  const header = req.get('x-wesign-signature') ?? req.get('x-letssign-signature')
  if (!verifyWeSignSignature(req.body, header, process.env.WESIGN_WEBHOOK_SECRET!)) {
    return res.status(401).end()
  }
  const eventId = req.get('x-wesign-event-id')!
  if (await alreadyProcessed(eventId)) return res.status(200).end()
  const event = JSON.parse(req.body.toString('utf8'))
  // … handle event.event …
  await markProcessed(eventId)
  res.status(200).end()
})

PHP

<?php
function verifyWeSignSignature(string $rawBody, ?string $header, string $secret, int $toleranceSec = 300): bool
{
    if ($header === null) {
        return false;
    }
    // t=<t>,v1=<hex>[,v1=<hex>] — two entries for 24 h after a secret rotation.
    $parts = explode(',', $header);
    if (!preg_match('/^t=(\d+)$/', $parts[0] ?? '', $m)) {
        return false;
    }
    $t = $m[1];
    if (abs(time() - (int) $t) > $toleranceSec) {
        return false; // replay protection
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach (array_slice($parts, 1) as $part) {
        if (str_starts_with($part, 'v1=') && hash_equals($expected, substr($part, 3))) {
            return true; // constant-time, any entry may match
        }
    }
    return false;
}

$rawBody = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_WESIGN_SIGNATURE'] ?? $_SERVER['HTTP_X_LETSSIGN_SIGNATURE'] ?? null;

if (!verifyWeSignSignature($rawBody, $header, getenv('WESIGN_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

$eventId = $_SERVER['HTTP_X_WESIGN_EVENT_ID'] ?? '';
if (alreadyProcessed($eventId)) {
    http_response_code(200);
    exit;
}

$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
// … handle $event['event'] …
markProcessed($eventId);
http_response_code(200);

A worked example, so you can pin a unit test. With secret whsec_test, t = 1790000000 and the 38-byte body {"event":"ping","event_id":"evt_test"}, the message is the string 1790000000.{"event":"ping","event_id":"evt_test"} and the header is:

X-WeSign-Signature: t=1790000000,v1=281995437b0317b37dd656119dd670cded7fc52a8b1379711d663c146ba78dd1

Check it with createHmac('sha256', 'whsec_test').update(message).digest('hex') in Node, or printf '%s' "$message" | openssl dgst -sha256 -hmac whsec_test in a shell. During a rotation window the same delivery is signed twice over the same message:

X-WeSign-Signature: t=1757404800,v1=<hex with the NEW secret>,v1=<hex with the OLD secret>

Both snippets above accept it with either secret; after the window the header is back to the single v1=.

Retries

Any 2xx answer is a delivery; we never retry it. Anything else — another status, no response within 10 seconds, a connection error — is a failure, and the delivery is retried on this schedule:

attempt 1   immediate
attempt 2   +1 minute
attempt 3   +5 minutes
attempt 4   +30 minutes
attempt 5   +2 hours
attempt 6   +6 hours
attempt 7   +12 hours
attempt 8   +24 hours    (final)

That is eight attempts over about 45 hours (the 12-hour step was added in the 2026-10-02 release; before, seven attempts over about 33 hours). Retries are fired by a scheduler that runs every 5 minutes, so a step can fire up to 5 minutes after its due time. Every attempt is re-signed with a fresh t; the event_id stays the same.

After the last attempt fails, the delivery is marked giving_up and is not sent again on its own. The delivery log shows it; once your endpoint is fixed, Redeliver it there or with POST /v1/hooks/{id}/deliveries/{delivery_id}/redeliver.

Acknowledge first, work after: answer 2xx as soon as the signature checks out and do the processing afterwards, so a slow step on your side never turns into a timeout and a retry.

Redirects are not followed: a 3xx from your endpoint is a failure and is retried, and the delivery log records where it pointed (redirect not followed: HTTP 308, Location: …). Point the hook at the final URL — a trailing slash counts.

We never switch a hook off because its deliveries fail; only you can, in the dashboard or with DELETE /v1/hooks/{id}.

Delivery log and redelivery

Every hook keeps a log of its last 100 deliveries — in the dashboard under Developers → Webhooks, and over the API:

GET https://api.wesign.now/v1/hooks/{id}/deliveries
Authorization: Bearer wsk_live_…

→ 200 { "deliveries": [
  { "id": "5d0c…", "event": "document.completed", "event_id": "evt_9b1d…",
    "document_id": "8a1e4f9a-…", "attempts": 2, "response_status": 200,
    "response_body": "ok", "latency_ms": 143, "status": "success",
    "created_at": "2026-10-02T09:14:03.410Z", "next_retry_at": null,
    "completed_at": "2026-10-02T09:15:12.006Z" },
  …
] }

Newest first. attempts counts the attempts so far; response_status and response_body (the first 500 characters) are what your endpoint answered on the last one — or our note when no answer came: network: … for a timeout or connection error, redirect not followed: HTTP 308, Location: … for a redirect. latency_ms is how long that attempt took. status is pending (waiting for next_retry_at), success or giving_up. The body we sent is not in the log. A replaced or switched-off hook keeps its log; a deleted hook's log goes with it.

To send one again — typically one that gave up while your endpoint was down:

POST https://api.wesign.now/v1/hooks/{id}/deliveries/{delivery_id}/redeliver
Authorization: Bearer wsk_live_…

→ 200 { "delivery_id": "5d0c…", "event_id": "evt_9b1d…", "status": "success",
        "response_status": 200, "latency_ms": 97 }

It is the same delivery: the same event_id and body, in the hook's current payload mode, signed afresh. One attempt is made at once; status is success, pending (it failed and carries on along the retry schedule) or giving_up (it failed with no retries left). A switched-off hook answers 409 hook_disabled — a hook replaced by a re-POST too, and its deliveries cannot be redelivered on the new hook either, so redeliver given-up deliveries before you re-POST a target_url. The dashboard's Redeliver button does the same.

Test pings and redeliveries go to https hooks only: a hook registered over http before the 2026-10-02 release still receives its events, but answers 409 https_required here. Each hook takes at most 10 test pings and redeliveries a minute, together; the next answers 429 rate_limited with Retry-After.

Idempotency on your side

The X-WeSign-Event-Id header (and the event_id field in the body) is a stable, unique string per event. Use it as a deduplication key in your handler — at-least-once delivery means you'll occasionally see the same event twice during retry overlaps. The snippets above show where the check goes: after the signature, before the work.

For document.completed, also deduplicate on document_id: the event is emitted once per document, but a database failure at the moment of completion can still repeat it with a new event_id.

A redelivery carries the event_id of the original delivery, so the same check covers it.

Order and reconciliation

Order. Each delivery is its own request and its retries run on their own, so events can arrive in any order: document.completed before a signing_request.signed, or a released signer's signing_request.sent before the previous signer's signing_request.signed. Act on event and the ids, never on arrival order; when order matters, read the current state with GET /v1/documents/{id}.

Reconcile. Rarely, an event cannot be recorded for delivery (a database failure at that moment) and is never sent: no delivery row, so no retry and nothing to redeliver. We are alerted. If every signer's signing_request.signed has arrived and no document.completed follows within a few minutes, read GET /v1/documents/{id} (status: "signed") or fetch the signed PDF with GET /v1/documents/{id}/signed. The same read settles any other event you expected and did not get. No endpoint lists documents, so reconcile from the document_ids you stored; the delivery log names the document_id of each of the hook's last 100 deliveries. See If the event did not come.

Testing a hook

POST /v1/hooks/{id}/test — or Send test on the hook in the dashboard — sends that one hook a signed ping, whatever events it subscribes to:

{ "event": "ping", "event_id": "evt_0f3c…", "created_at": "2026-10-02T08:00:00.000Z" }

It carries the usual headers and signature, is attempted once and never retried, and the response tells you how it went:

POST https://api.wesign.now/v1/hooks/{id}/test
Authorization: Bearer wsk_live_…

→ 200 { "delivery_id": "…", "event_id": "evt_0f3c…", "status": "success",
        "response_status": 200, "latency_ms": 84 }

status is success when your endpoint answered 2xx, else giving_up (with your response_status, or null when no answer came). ping is not an event type you can subscribe to; answer it 2xx like any event you do not handle. A switched-off hook answers 409 hook_disabled; the https rule and the limit of 10 a minute per hook are the same as for redelivery. Before the 2026-10-02 release, Send test sent a synthetic signing_request.sent with "test": true instead.

REST hooks (for connectors)

Integrators and no-code tools (Zapier, Make) manage subscriptions over the API instead of in the dashboard, with a full API key (Key scopes):

POST https://api.wesign.now/v1/hooks
Authorization: Bearer wsk_live_…
Content-Type: application/json

{ "target_url": "https://yourapp.example/wesign",
  "events": ["signing_request.signed", "signing_request.declined", "signing_request.expired", "document.completed"],
  "payload": "minimal" }

→ 200 { "id": "…", "target_url": "https://yourapp.example/wesign",
        "events": ["signing_request.signed", "signing_request.declined", "signing_request.expired", "document.completed"],
        "enabled": true, "created_at": "…", "payload": "minimal",
        "secret": "whsec_…", "replaced_hook_ids": [] }

GET    https://api.wesign.now/v1/hooks                            # your active hooks
GET    https://api.wesign.now/v1/hooks?include_disabled=true      # … plus the switched-off ones
DELETE https://api.wesign.now/v1/hooks/{id}                       # unsubscribe → 204, no body
POST   https://api.wesign.now/v1/hooks/{id}/rotate                # new signing secret, 24 h overlap
GET    https://api.wesign.now/v1/hooks/{id}/deliveries            # the delivery log
POST   https://api.wesign.now/v1/hooks/{id}/deliveries/{delivery_id}/redeliver
POST   https://api.wesign.now/v1/hooks/{id}/test                  # a signed ping

target_url must be https: anything else answers 400 https_required. A host that is, or resolves to, a private, loopback, link-local (such as 169.254.169.254), CGNAT or reserved address — or localhost, *.local, *.internal, or a name that does not resolve — answers 400 url_not_public. The address is checked again at every delivery.

events: an empty or omitted list subscribes to all event types, including ones added later; up to ten named events otherwise. An unknown name answers 400 unknown_event and lists the valid ones:

{ "error": "Unknown event name: signing_request.signedd. Valid events: signing_request.sent, …",
  "code": "unknown_event",
  "meta": { "unknown": ["signing_request.signedd"],
            "valid_events": ["signing_request.sent", "signing_request.viewed", "…"] } }

payload: "full" (default) or "minimal" — see Payload modes. On a re-POST that replaces a minimal hook, leaving payload out keeps the new hook minimal, so a request body written before this field existed never turns personal data back on; send "full" to switch back. events is not carried over: left out, it means every event.

The same target_url again replaces the hook. When an active workspace-wide hook of your workspace already targets the URL, it is switched off — it drops out of GET /v1/hooks and receives nothing more — and the call returns the new hook with a new id and a new secret, naming the old one in replaced_hook_ids. That is how you change a hook's events or payload mode. Deliveries of the old hook still being retried, for events the new hook subscribes to, move to the new hook with their event_id, so nothing is lost in the switch; switch your receiver to the new secret right away. Deliveries that had already given up stay in the old hook's log, which stays readable but cannot redeliver: redeliver them before you re-POST. URLs are compared parsed: the case of scheme and host and a default port do not matter, but the path does, a trailing slash and the query string included. Two registrations that race leave the newest active. A workspace-wide hook created in the dashboard on the same URL is replaced too; a document-scoped callback_url hook never is, and creating a hook in the dashboard replaces nothing.

The create answers 200 (not 201), and secret is in that response only.

Listing. GET /v1/hooks lists active hooks only, newest first, each with id, target_url, events, enabled, created_at and payload, never the secret. A hook missing from the default list is inactive: deleted, replaced, or switched off in the dashboard. Pass exactly include_disabled=true to also get the switched-off ones (enabled: false), so an "is my hook set up?" check can answer it exists but is disabled instead of creating a duplicate. There is no GET /v1/hooks/{id} — list and filter by id. We never switch a hook off on our own because its deliveries fail.

Unsubscribing. DELETE /v1/hooks/{id} answers 204 with no body — also for an unknown id or another workspace's hook, where nothing is deleted. The delivery log goes with the hook.

Rotating a secret

POST https://api.wesign.now/v1/hooks/{id}/rotate
Authorization: Bearer wsk_live_…

→ 200 {
  "id": "…",
  "secret": "whsec_…",
  "secret_prefix": "whsec_ab12cd34",
  "previous_secret_valid_until": "2026-09-17T12:00:00.000Z"
}

No body. The response carries the new secret once. Until previous_secret_valid_until — a fixed 24 hours — every delivery is signed with both secrets, new first:

X-WeSign-Signature:   t=1757404800,v1=<hmac with new secret>,v1=<hmac with old secret>
X-LetsSign-Signature: t=1757404800,v1=<hmac with new secret>,v1=<hmac with old secret>

A receiver that tries every v1= entry keeps verifying with the old secret throughout the window and switches whenever it likes. After the window the header is back to a single v1=. Rotating again inside the window replaces the previous secret — the older one stops verifying immediately, so at most two secrets are ever live.

Rotation works on any workspace-wide hook, whether it was created here or in the dashboard, enabled or disabled. 404 not_found for an unknown id, a hook of another workspace, or a document-scoped callback_url hook; 409 rotation_conflict if two rotations raced — retry, the other call's secret is the live one.