Skip to content

Webhooks

Every webhook event type, the delivery body, how to verify the signature, the retry schedule and how to handle deliveries idempotently.

Esign Comply sends a signed HTTPS POST to your endpoint when something happens to a record, a session, a document, a domain or your guidance. Use the record.completed event, or GET /v1/records/{id} with a secret key, to confirm a record before your application grants access. See Server confirmation.

Endpoints are created and managed with the API or in the dashboard: see Account. Each endpoint has its own signing secret (whsec_...), shown once when the endpoint is created. Store it as ESIGNCOMPLY_WEBHOOK_SECRET on your server.

Delivery

Every delivery is a POST with a JSON body and three signature headers.

POST /api/esigncomply/webhook HTTP/1.1
Host: app.example.com
Content-Type: application/json
User-Agent: EsignComply-Webhooks/1.0
webhook-id: whe_3Jk9pQ2m
webhook-timestamp: 1795273401
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQm...

{
  "object": "event",
  "id": "whe_3Jk9pQ2m",
  "type": "record.completed",
  "api_version": "2026-11-21",
  "livemode": false,
  "created_at": "2026-11-21T15:03:21.104Z",
  "data": {
    "record_id": "rec_Z4m8",
    "session_id": "ses_5nWq",
    "signer_external_id": "user_7c1d",
    "status": "recorded",
    "record_hash": "sha256:5be7...",
    "signed_at": "2026-11-21T15:03:20.291Z",
    "assurance_level": "L1",
    "signature_level": "simple",
    "documents": [
      { "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." },
      { "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." }
    ],
    "purpose": "account_signup"
  }
}
Field Meaning
object Always event
id The event ID. The same value as the webhook-id header, and the same on every retry of this delivery.
type The event type
api_version The API version the endpoint is pinned to: the version in force when the endpoint was created
livemode true for live events, false for test events. Test endpoints receive test events only.
created_at When the event was created
data IDs and status for the event type

Payloads carry IDs and status. The only personal datum is the signer's external ID. Fetch the record with a secret key when you need more.

Verify the signature

Deliveries follow the Standard Webhooks convention. The signature is an HMAC-SHA256 over the string <webhook-id>.<webhook-timestamp>.<raw body>. The key is the base64-decoded part of the secret after whsec_. The header value is v1, followed by the base64 signature, and it may hold several space-separated signatures while a secret is being rotated.

Three rules:

  1. Verify against the raw request body, byte for byte. Do not parse and re-serialize the JSON first.
  2. Reject a delivery whose webhook-timestamp is more than 5 minutes from now.
  3. Compare signatures in constant time.

With the server SDK:

// app/api/esigncomply/webhook/route.ts
import { esc } from "@/lib/esigncomply";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const { data: event, error } = await esc.webhooks.verify(
    rawBody,
    request.headers,
    process.env.ESIGNCOMPLY_WEBHOOK_SECRET!,
  );
  if (error) return new Response("Invalid signature", { status: 400 });

  // Deliveries are at-least-once: do the work once per event ID.
  const firstTime = await rememberWebhookEvent(event.id);
  if (!firstTime) return new Response(null, { status: 200 });

  switch (event.type) {
    case "record.completed":
      await confirmAndUnlock(event.data.record_id as string);
      break;
    case "record.disputed":
      await flagRecord(event.data.record_id as string);
      break;
    default:
      // Ignore event types you do not know.
      break;
  }
  return new Response(null, { status: 200 });
}

rememberWebhookEvent, confirmAndUnlock and flagRecord are yours. rememberWebhookEvent inserts the event ID into a table with a unique constraint and returns false when the row already exists.

Without the SDK, in Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyEsignComplyWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get("webhook-id");
  const timestamp = headers.get("webhook-timestamp");
  const signature = headers.get("webhook-signature");
  if (!id || !timestamp || !signature) return false;

  // Reject deliveries more than 5 minutes old (or from the future).
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return signature.split(" ").some((part) => {
    const [version, value] = part.split(",");
    if (version !== "v1" || !value) return false;
    const received = Buffer.from(value, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Return 400 when verification fails. Do not act on an unverified body.

Respond

Return any 2xx status to acknowledge a delivery. Respond within 5 seconds: do slow work after you have answered, or in a queue. A delivery that gets no answer in 10 seconds, a redirect, or a status outside 2xx counts as failed and is retried.

Retries

A failed delivery is retried with growing delays: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, then every 12 hours. After the last retry, about 64 hours after the first attempt, the delivery is marked failed.

An endpoint that fails continuously for 5 days is disabled, and the organization's owners are told by email. Enable it again in the dashboard or with PATCH /v1/webhooks/{id} once it answers.

Because a record can be confirmed with GET /v1/records/{id} at any time, a missed webhook never loses a record. Reconcile after an outage by listing records created since the last event you processed.

Idempotency and order

  • Deliveries are at-least-once. The same event can arrive more than once, with the same webhook-id. Make the handler idempotent on that ID.
  • Order is not guaranteed. record.timestamped can arrive before your handler has finished record.completed. Treat each event as a statement about the object, and read the object when you need its current state.
  • New event types may be added at any time. An endpoint receives a type only if it subscribes to that type or to all events ("*"). Ignore types you do not know and return 200.

Event types

An endpoint subscribes to a list of types, or to "*" for all of them. A type that is not in this list is refused when the endpoint is created.

Sessions

Type Sent when data
session.expired A session reached its lifetime without a record session_id
session.cancelled A session was cancelled without a record session_id, cancelled_by (signer, customer or system), and reason: "verification_failed" when a verification lockout ended it

Records

Type Sent when data
record.completed A record is durably written and its receipt signed. Use this to unlock access. record_id, session_id, signer_external_id, status, record_hash, signed_at, assurance_level, signature_level, documents[] (version_id, content_hash), purpose
record.timestamped The external timestamp token is attached record_id, status, timestamp_time
record.anchored The record is included in a published checkpoint record_id, status
record.copy_delivered The signer's receipt email was delivered record_id, signer_external_id
record.copy_bounced The signer's receipt email bounced record_id, signer_external_id, reason
record.disputed The signer used "This was not me" from the receipt record_id

record.completed is sent only once the receipt exists. A record that was committed while the signing key service was unreachable is pending_seal for up to 60 seconds, and the event follows when the receipt is signed.

Type Sent when data
consent.withdrawn A signer withdrew consent to electronic records record_id, and signer_external_id when the withdrawal came through the API
signer.electronic_transactions_refused A signer used the receipt's request to stop future electronic transactions The signer's external ID and the record the request was made from
signer.reacceptance_required A new version with material_change: true leaves a signer outstanding signer_external_id, document_id, version_id

Documents and domains

Type Sent when data
document.version_published A new document version was published document_id, version_id, version_label, language, material_change, effective_at
domain.verified The domain passed verification domain_id, domain
domain.verification_lapsed Three daily checks in a row failed for a verified domain domain_id, domain, live_recording_until

Usage and conformance

Type Sent when data
usage.threshold_reached Live signature events reached 50%, 80%, 90% or 100% of the plan's limit, on Free and Starter. threshold is 50, 80, 90 or 100. See Free plan limits and Starter limits. threshold, used, quota, period_end
conformance.run_completed A conformance run finished run_id, status, block, warn

Certificates

Type Sent when data
certificate.issued An on-request certificate was issued certificate_id, type, record_count, requested_by.class
certificate.failed An integrity check stopped a certificate. Nothing was issued. record_id, failed_checks, request_id
certificate.charged A certificate was charged certificate_id, units, amount, currency
certificate.spend_threshold_reached The month's certificate spend reached 80% or 100% of the limit threshold, month_to_date, spend_limit

Supplements

Type Sent when data
supplement.received Customer-supplied material was accepted supplement_id, subject, type, content_hash
supplement.sealed The supplement's external timestamp was attached supplement_id, content_hash, timestamp_time
supplement.withdrawn A supplement was withdrawn supplement_id, subject_type, subject_id, type, content_hash, withdrawn_by

supplement.withdrawn is queued in the same transaction as the withdrawal. subject_type is record, session, signer, document_version or domain, and subject_id is the ID of that object (null for the domain). For a signer it is Esign Comply's own ID of the signer, not your external_id: read the supplement with GET /v1/supplements/{id} for its subject as you sent it. withdrawn_by names the key or member that withdrew it, for example key:key_2bQ1.

{
  "object": "event",
  "id": "whe_8Qw2tR5n",
  "type": "supplement.withdrawn",
  "api_version": "2026-11-21",
  "livemode": true,
  "created_at": "2027-01-06T10:12:44.018Z",
  "data": {
    "supplement_id": "sup_9Lm3",
    "subject_type": "record",
    "subject_id": "rec_Z4m8",
    "type": "notice.sent",
    "content_hash": "sha256:5d0c...",
    "withdrawn_by": "key:key_2bQ1"
  }
}

Guidance, packs and profiles

Type Sent when data
guidance.notice_published A notice that targets the domain was published notice_id, kind, class, severity, jurisdictions, effective_at, affected_profiles, update_prompt
guidance.release_published A guidance release was published that concerns the domain release_id, content_hash, published_at, added, changed, retired, jurisdictions, url
jurisdiction.pack_updated A new version of a pack enabled on one of the domain's profiles was published code, previous_version, version, effective_at, guidance_release, adds_block_rule, adds_required_step, affected_profiles
profile.adoption_available A guidance release left a profile with record conditions waiting in advise profile_id, profile_version, guidance_release, pending_rules, pack_versions, url
profile.adopted A member or key adopted pending record conditions profile_id, profile_version, baseline, adopted_rules, adopted_by
profile.rolled_back A profile returned to its previous baseline profile_id, profile_version, baseline, rolled_back_by

Where the data column lists field names in code, those are the fields the current API sends. Where it is described in words, read the payload defensively: the field names are not fixed yet.

The three release events are sent when a guidance release is published, before its notices. They carry IDs, codes, versions and URLs only: read the release, the pack or the profile for the detail.

guidance.release_published is sent once per release to each domain the release concerns: a pack it publishes, or a jurisdiction of one of its notices, is enabled on one of the domain's profiles or is on its watched list. It is sent in both environments.

Field Description
release_id The release, for example 2026.12.1. Read it with GET /v1/guidance/releases/{id}.
content_hash SHA-256 of the release content, as signed.
published_at When the release was published.
added, changed, retired The counts of items added, changed and retired, as in the release's changelog.
jurisdictions The codes of the release that put it in scope for this domain.
url The API URL of the release.
{
  "release_id": "2026.12.1",
  "content_hash": "sha256:77eb...",
  "published_at": "2026-12-01T09:00:00.000Z",
  "added": 0,
  "changed": 1,
  "retired": 0,
  "jurisdictions": ["US-CA"],
  "url": "https://esigncomply.com/v1/guidance/releases/2026.12.1"
}

jurisdiction.pack_updated is sent once for each new version of a pack that at least one profile of the domain enables, in the environment of those profiles. A state pack implies US-FED, so a profile that enables US-CA is also affected by a new US-FED version. The first version of a pack sends nothing.

Field Description
code The pack code.
previous_version, version The version before, and the version published.
effective_at When the new version takes effect.
guidance_release The release that published it.
adds_block_rule true when the version adds a record condition at Block level, or raises one to Block.
adds_required_step true when a record condition of the version adds a step to required_steps once adopted.
affected_profiles IDs of the profiles in this environment that enable the pack.
{
  "code": "US-CA",
  "previous_version": "2026-11-21",
  "version": "2026-12-01",
  "effective_at": "2026-12-01T00:00:00.000Z",
  "guidance_release": "2026.12.1",
  "adds_block_rule": true,
  "adds_required_step": false,
  "affected_profiles": ["prof_signup_4f1a"]
}

profile.adoption_available is sent once per release for each profile that gained record conditions from it. The conditions are in advise: they are evaluated and stored, and they do not refuse a record or add a step until you adopt them.

Field Description
profile_id, profile_version The profile and its current version.
guidance_release The release that brought the conditions.
pending_rules Rule IDs of every record condition now waiting for adoption on the profile. The same list as pending_conditions on GET /v1/profiles/{id}.
pack_versions For each pack with a pending condition, the version the condition comes from.
url The dashboard page where a member reviews and adopts the conditions.
{
  "profile_id": "prof_signup_4f1a",
  "profile_version": 3,
  "guidance_release": "2026.12.1",
  "pending_rules": ["CA-07", "CA-08"],
  "pack_versions": { "US-CA": "2026-12-01" },
  "url": "https://esigncomply.com/dashboard/profiles/prof_signup_4f1a/adopt"
}

A guidance event never changes how recording works. A new Block rule or required step from a pack update starts in advise for existing profiles and does not affect recording until you adopt it. Forward guidance.notice_published to a person, and do not change application behavior in the handler. See Guidance and adoption.

Test your handler

  • With a test key, every ceremony you run on localhost produces test events. Use the reserved test signer addresses to force outcomes such as a bounce or a dispute. See Test mode.
  • POST /v1/webhooks/{id}/test sends one signed webhook.test event to the endpoint and returns what the endpoint answered.
  • The CLI forwards test deliveries to a local server while you develop. See CLI.
  • Test endpoints may use http://localhost. Live endpoints must use HTTPS on a public host.

Checklist

  • The handler reads the raw body and verifies the signature before anything else.
  • It rejects timestamps more than 5 minutes old.
  • It is idempotent on webhook-id.
  • It returns 2xx within 5 seconds and ignores unknown types.
  • record.completed leads to the same checks as server confirmation: status, livemode, signer and document versions against state your server owns.
  • The secret is in a server environment variable and nowhere else.