# Webhooks

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

Source: https://esigncomply.com/docs/api/webhooks

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](https://esigncomply.com/docs/guides/server-confirmation.md).

Endpoints are created and managed with the API or in the dashboard: see [Account](https://esigncomply.com/docs/api/account.md). 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.

```http
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](https://www.standardwebhooks.com/) 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:

```ts
// 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:

```ts
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.

### 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](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits) and [Starter limits](https://esigncomply.com/docs/guides/test-mode.md#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`.

```json
{
  "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](https://esigncomply.com/docs/api/guidance.md#set-watched-jurisdictions). 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. |

```json
{
  "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. |

```json
{
  "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](https://esigncomply.com/docs/api/guidance.md) 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. |

```json
{
  "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](https://esigncomply.com/docs/guides/guidance.md).

## 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](https://esigncomply.com/docs/guides/test-mode.md).
- `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](https://esigncomply.com/docs/sdk/cli.md).
- 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](https://esigncomply.com/docs/guides/server-confirmation.md): status, `livemode`, signer and document versions against state your server owns.
- The secret is in a server environment variable and nowhere else.
