Webhooks

Instead of polling, subscribe a webhook so Craftkit pushes state changes to your server. Four event families are delivered: render.* (rendering lifecycle), document.* (engagement on a delivered document), signature.* (e-signature lifecycle), and form.* (collect-only embed fill submissions).

Looking to trigger a render from an external system instead? That’s the inbound webhook (POST /v1/hooks/:token) — see Inbound webhook.

Configure a subscription

Webhooks are configured per project in the dashboard (Project → Webhooks): a url, a signing secret, the list of events to subscribe to, and an active flag. There is no API to register subscriptions programmatically yet (roadmap) — use the dashboard. A subscription only receives the events it is subscribed to; run several subscriptions (each with its own secret) to split traffic by family.

Event triggers

Every event name is family.action.

`render.*`

Event	Fired when
`render.succeeded`	a render finished and the PDF is available
`render.failed`	a render terminated with an error (`errorMessage` explains why)

`document.*`

Fired as recipients interact with a render you’ve shared or emailed (see Sharing). Recipient-facing events (viewed/downloaded/printed/email_opened) are de-duplicated within a 5-minute window per (share, event, source IP).

Event	Fired when
`document.share_created`	a share link was created for a render
`document.share_revoked`	a share link was revoked
`document.email_sent`	the render was emailed to a recipient
`document.email_opened`	a recipient opened the delivery email
`document.viewed`	a recipient opened the shared document
`document.downloaded`	a recipient downloaded the PDF
`document.printed`	a recipient printed the document

`signature.*`

Fired as a signature request progresses. Payloads are provider-neutral — Craftkit’s own status vocabulary only, never a third-party event type or id.

Event	Fired when
`signature.sent`	a signature request was created and recipients were emailed
`signature.viewed`	a recipient opened the signing UI
`signature.signed`	a single recipient signed (per-recipient; top-level status unchanged)
`signature.completed`	all recipients signed and the document is finalized
`signature.declined`	a recipient declined to sign
`signature.expired`	the request passed its expiration window
`signature.cancelled`	the request was cancelled

`form.*`

Emitted by embed fill sessions minted with form.captureMode: "collect" (see Embed sessions). In collect-only mode the form is pure data-collection infrastructure: on submit Craftkit validates the field data and delivers it to you without creating a render or storing the field data. You persist it and request the render as a separate follow-up call.

Event	Fired when
`form.submitted`	a collect-only fill form was submitted and validated

form.submitted is ephemeral: because collect-only mode retains nothing, the delivery payload (which carries the submitted field data) is held only until you 2xx it — through the normal retry/backoff — then it is purged. There is no pull fallback: the webhook is the only delivery path. Alert on a delivery that exhausts its retries (abandoned), since after that the payload is gone.

At-least-once, no replay. The collect submit returns 202 only after the form.submitted delivery is durably enqueued — but a 503/500 from the submit endpoint may still have enqueued (and delivered) it, so treat form.submitted as at-least-once. A submit retry mints a new delivery, so x-craftkit-delivery-id won’t match across a resubmit — dedupe on the payload’s sessionId (stable per fill), not on the delivery id alone. And because an abandoned delivery is purged it cannot be replayed: keep your endpoint reachable and rely on your own retry.

Delivery contract

Craftkit POSTs a JSON body to your url with these headers:

Header	Value
`x-craftkit-event`	the event name (mirrors the body’s `event` field)
`x-craftkit-signature`	HMAC-SHA256 of the raw body, hex-encoded, keyed by the subscription secret
`x-craftkit-timestamp`	unix seconds when the delivery was signed
`x-craftkit-delivery-id`	stable delivery id — reused across retries; use for idempotency
`user-agent`	`Craftkit-Webhook/1.0`

Every body is a JSON object whose first field is event; the rest depends on the family.

render.*
document.*
signature.*
form.*

string

render.succeeded or render.failed.

string

Terminal render status.

string | null

Public PDF URL on success; null when public delivery isn’t configured or on failure.

string | null

Set on render.failed.

string

string | null

{
  "event": "render.succeeded",
  "renderId": "…",
  "templateId": "…",
  "status": "succeeded",
  "downloadUrl": "https://…/renders/…/….pdf",
  "errorMessage": null,
  "createdAt": "2026-06-05T10:00:00.000Z",
  "completedAt": "2026-06-05T10:00:03.120Z"
}

string

The document.* event name.

string

The share link involved, if any.

string

Id of the recorded engagement event.

string

Bare engagement type (viewed, downloaded, printed, email_opened, email_sent, share_created, share_revoked).

string

recipient, partner, or system.

string | null

object | null

Custom metadata attached when the event was recorded.

string

{
  "event": "document.viewed",
  "renderId": "…",
  "templateId": "…",
  "shareId": "…",
  "eventId": "…",
  "eventType": "viewed",
  "actorKind": "recipient",
  "sourceIp": "203.0.113.7",
  "userAgent": "Mozilla/5.0 …",
  "metadata": null,
  "createdAt": "2026-06-05T11:03:00.000Z"
}

string

The signature.* event name.

string

Provider-neutral request status. Present on lifecycle events.

string

Request name. Present on signature.sent.

array

Recipient snapshot. Present on signature.sent.

string | null

Decline/cancel reason, when provided.

Only event, signatureRequestId, and renderId are guaranteed on every signature event.

{
  "event": "signature.completed",
  "signatureRequestId": "…",
  "renderId": "…",
  "status": "completed"
}

string

form.submitted.

string

The embed fill session that produced the submission.

string

Slug of the template the form was scoped to.

number

Published version number the data was validated against.

string | null

null in collect-only mode (no render was created).

object

The complete merged, manifest-keyed, coerced field set (prefill + user entries, user wins). Same shape the render API accepts, so you can store-then-render with it verbatim.

string

ISO-8601 timestamp of the submission.

The payload is retained only until you 2xx it, then purged (see the retention warning above).

{
  "event": "form.submitted",
  "sessionId": "…",
  "templateSlug": "e-charterparty",
  "templateVersion": 6,
  "renderId": null,
  "data": { "customer": { "name": "Acme Corp" }, "amount": 42 },
  "submittedAt": "2026-06-05T11:00:00.000Z"
}

Verify the signature

Compute the HMAC over the raw request body and compare against x-craftkit-signature (raw hex, no sha256= prefix) in constant time. Reject on mismatch. Optionally reject deliveries whose x-craftkit-timestamp is outside a tolerance window to blunt replays.

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

app.post('/webhooks/craftkit', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac('sha256', process.env.CK_WEBHOOK_SECRET)
    .update(req.body) // raw Buffer
    .digest('hex');
  const got = req.header('x-craftkit-signature') ?? '';
  const ok =
    expected.length === got.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(got));
  if (!ok) return res.status(401).end();

  const evt = JSON.parse(req.body.toString());
  switch (evt.event) {
    case 'render.succeeded':
      storeDownloadUrl(evt.renderId, evt.downloadUrl);
      break;
    case 'document.viewed':
      trackEngagement(evt.renderId, evt.eventType, evt.actorKind);
      break;
    case 'signature.completed':
      markSigned(evt.signatureRequestId);
      break;
  }
  res.json({ received: true }); // return 2xx promptly
});

Retries

Failed deliveries (non-2xx, timeout, or error) retry up to 6 attempts; after that the delivery is marked abandoned. Respond 2xx quickly (the budget is ~15s per attempt) and do heavy work asynchronously. De-duplicate on x-craftkit-delivery-id since a delivery may arrive more than once.

downloadUrl in render.* payloads follows the same durability rules as elsewhere — a permanent public URL, or null if no public bucket is configured. See Render lifecycle.

Get started

Server-to-server integration

Configure a subscription

Event triggers

`render.*`

`document.*`

`signature.*`

`form.*`

Delivery contract

Verify the signature

Retries

​Configure a subscription

​Event triggers

​render.*

​document.*

​signature.*

​form.*

​Delivery contract

​Verify the signature

​Retries

Configure a subscription

Event triggers

`render.*`

`document.*`

`signature.*`

`form.*`

Delivery contract

Verify the signature

Retries