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:
- Verify against the raw request body, byte for byte. Do not parse and re-serialize the JSON first.
- Reject a delivery whose
webhook-timestampis more than 5 minutes from now. - 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.timestampedcan arrive before your handler has finishedrecord.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 return200.
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.
Signers and consent
| 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
localhostproduces 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}/testsends one signedwebhook.testevent 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
2xxwithin 5 seconds and ignores unknown types. record.completedleads 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.