Webhooks

sajn can send webhook notifications to your server when events occur in your account. This allows you to build integrations that react to document signings, contact changes, identity checks, and more.

Setup

Webhooks are configured per workspace under Settings > Developer > Webhooks. When creating a webhook you provide:

Field	Required	Description
URL	Yes	The endpoint that will receive POST requests. Must be publicly reachable (HTTPS recommended).
Events	Yes	Which events to subscribe to.
Secret	No	A shared secret sent in the `X-Sajn-Secret` header so you can verify requests.

The URL is validated on creation — sajn will resolve the hostname, block private/internal IPs (SSRF protection), and send a test POST to confirm the endpoint is reachable.

Request Format

All webhooks are sent as POST requests with a JSON body:

{
  "event": "DOCUMENT_SIGNED",
  "payload": { ... },
  "createdAt": "2026-04-16T12:00:00.000Z",
  "webhookEndpoint": "https://your-server.com/webhook"
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-Sajn-Secret`	The secret you configured (empty string if not set). Use this to verify that the request came from sajn.
`X-Sajn-Environment`	`sandbox` for deliveries from a sandbox organization, `production` for everything else. Useful when both environments post to the same endpoint.

Verifying Requests

Compare the X-Sajn-Secret header value against the secret you configured when creating the webhook. Reject requests that don’t match.

Handling New Fields

Payloads gain fields over time as sajn adds features. Adding a field is not treated as a breaking change, so your endpoint must ignore keys it does not recognise. Most JSON parsers do this by default; strict deserialisers do not, so check the ones that reject unknown properties — zod schemas using .strict(), Pydantic models with extra="forbid", JSON Schema validation with additionalProperties: false, Go’s DisallowUnknownFields(), and Jackson, where FAIL_ON_UNKNOWN_PROPERTIES is enabled unless you turn it off. Existing fields are never removed or retyped without a new API version.

Delivery

Webhooks are dispatched asynchronously via a background job queue.
Each webhook call is logged with request/response details and kept for 72 hours.
If delivery fails (network error or non-2xx response), an in-app notification is sent to organization members who have enabled webhook failure notifications.
There is no automatic retry. If delivery fails, you can inspect the call log in the dashboard and resend manually or handle it on your end.

Events

Document Events

These events fire on document-level state changes. The payload is a Document object.

Event	Description
`DOCUMENT_CREATED`	A new document was created.
`DOCUMENT_SENT`	The document was sent out to its signers.
`DOCUMENT_SIGNED`	All signers have signed the document.
`DOCUMENT_COMPLETED`	The document has been sealed and is fully completed.
`DOCUMENT_REJECTED`	The document was rejected (by any signer).
`DOCUMENT_EXPIRED`	The document passed its expiration date while still pending.
`DOCUMENT_WITHDRAWN`	The document was withdrawn by the sender.
`DOCUMENT_MODIFIED`	An already-sent document was updated in place.
`DOCUMENT_EXPIRATION_EXTENDED`	The document’s expiration date was pushed further out.
`DOCUMENT_DELETED`	The document was moved to trash.
`DOCUMENT_RESTORED`	The document was restored from trash.
`DOCUMENT_ARCHIVED`	The document was archived.
`DOCUMENT_UNARCHIVED`	The document was taken out of the archive.
`DOCUMENT_ARCHIVE_UPLOADED`	A document was created from an inbound email attachment.

Party Events (per signer)

These events fire when a specific party takes action. The payload is a Document + Party object.

Event	Description
`DOCUMENT_PARTY_SENT`	The signing notification was sent to a signer.
`DOCUMENT_PARTY_DELIVERY_FAILED`	The signing notification failed to deliver to a signer.
`DOCUMENT_PARTY_OPENED`	A signer opened the signing link.
`DOCUMENT_PARTY_READ`	A signer read/scrolled through the document.
`DOCUMENT_PARTY_SIGNED`	A signer signed the document.
`DOCUMENT_PARTY_REJECTED`	A signer rejected the document.
`DOCUMENT_PARTY_ADDED`	A signer was added to an already-sent document.
`DOCUMENT_PARTY_REMOVED`	A signer was removed from an already-sent document.
`DOCUMENT_PARTY_DELEGATED`	A signer delegated their signature to someone else.
`DOCUMENT_PARTY_AUTH_FAILED`	A signer failed the verification step guarding the document.

Reminder Events

Reminder events also use the Document + Party object.

Event	Description
`DOCUMENT_REMINDER_AUTOMATIC`	An automatic scheduled reminder was sent to a signer.
`DOCUMENT_REMINDER_MANUAL`	A manual reminder was sent to a signer by the document owner.

Identity Check Events

These events fire during the identity verification flow. The payload is an Identity Check object.

Event	Description
`ID_CREATED`	A new identity check was initiated.
`ID_SENT`	The verification link was sent (via email or SMS).
`ID_OPENED`	The verification link was opened.
`ID_VERIFIED`	The identity was successfully verified (e.g. BankID).
`ID_FAILED`	The identity verification failed.
`ID_CANCELED`	The identity check was canceled.

Contact Events

These events fire when contacts are modified. The payload is a Contact object.

Event	Description
`CONTACT_CREATED`	A new contact was created.
`CONTACT_UPDATED`	A contact’s details were updated.
`CONTACT_DELETED`	A contact was deleted.

Template Events

Event	Description
`TEMPLATE_CREATED`	A new template was created.
`TEMPLATE_UPDATED`	A template was updated.
`TEMPLATE_DELETED`	A template was moved to trash.
`TEMPLATE_RESTORED`	A template was restored from trash.

Workspace Events

Event	Description
`WORKSPACE_CREATED`	A new workspace was created.
`MEMBER_ADDED`	A member was added to the organization or a workspace.

A handful of enum values exist in the schema but never fire and cannot be subscribed to: DOCUMENT_OPENED (legacy — use DOCUMENT_PARTY_OPENED), DOCUMENT_RECREATED (retired — the in-place update fires DOCUMENT_MODIFIED instead), and WORKFLOW_STARTED / WORKFLOW_COMPLETED / WORKFLOW_FAILED (reserved for the workflows beta).

Payloads

Document Payload

Used by document-level events (DOCUMENT_CREATED, DOCUMENT_SENT, DOCUMENT_SIGNED, DOCUMENT_COMPLETED, DOCUMENT_REJECTED, DOCUMENT_EXPIRED, DOCUMENT_WITHDRAWN).

{
  "id": "clx1abc...",
  "title": "Employment Agreement",
  "externalId": "booking-4711",
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:00:00.000Z",
  "organizationId": "clx2def...",
  "status": "COMPLETED",
  "parties": [
    {
      "id": "clx3ghi...",
      "name": "Anna Svensson",
      "email": "[email protected]",
      "externalId": "customer-88",
      "signingStatus": "SIGNED"
    }
  ],
  "signers": [...]
}

Field	Type	Description
`id`	string	Document ID.
`title`	string	Document title.
`externalId`	string or null	Your own reference ID for the document, as set when it was created or updated.
`createdAt`	string (ISO 8601)	When the document was created.
`updatedAt`	string (ISO 8601)	When the document was last updated.
`organizationId`	string	The organization that owns the document.
`status`	string	One of: `DRAFT`, `SENDING`, `PENDING_APPROVAL`, `PENDING`, `COMPLETED`, `EXPIRED`, `CANCELLED`, `REJECTED`, `IMPORTED`.
`parties`	array	The document’s participants (see below).
`signers`	array	Deprecated. Identical content to `parties`, kept for older integrations. Removed in API v2 — see Migrating from Signers to Parties.

Party object:

Field	Type	Description
`id`	string	Party ID.
`name`	string	The party’s name.
`email`	string	The party’s email address.
`externalId`	string or null	Your own reference ID for the party, as set when it was added to the document.
`signingStatus`	string	One of: `NOT_SIGNED`, `SIGNED`, `REJECTED`.

Document + Party Payload

Used by party-level and reminder events. Wraps the document payload with the specific party that triggered the event.

{
  "document": {
    "id": "clx1abc...",
    "title": "Employment Agreement",
    "externalId": "booking-4711",
    "createdAt": "2026-04-16T10:00:00.000Z",
    "updatedAt": "2026-04-16T12:00:00.000Z",
    "organizationId": "clx2def...",
    "status": "PENDING",
    "parties": [...],
    "signers": [...]
  },
  "party": {
    "id": "clx3ghi...",
    "name": "Anna Svensson",
    "email": "[email protected]",
    "externalId": "customer-88",
    "signingStatus": "SIGNED"
  }
}

Field	Type	Description
`document`	object	The full Document payload.
`party`	object	The party that triggered this event (same shape as a party object).

Identity Check Payload

Used by identity check events (ID_CREATED, ID_SENT, ID_OPENED, ID_VERIFIED, ID_FAILED, ID_CANCELED).

{
  "id": "clx4jkl...",
  "fullName": "Erik Johansson",
  "email": "[email protected]",
  "phone": "+46701234567",
  "channel": "EMAIL",
  "reference": "ref-123",
  "status": "VERIFIED",
  "failureReason": null,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:30:00.000Z",
  "organizationId": "clx2def...",
  "contactId": "clx5mno..."
}

Field	Type	Description
`id`	string	Identity check ID.
`fullName`	string	Full name of the person being verified.
`email`	string or null	Email address.
`phone`	string or null	Phone number.
`channel`	string	Delivery channel: `EMAIL`, `SMS`, or `IN_APP`.
`reference`	string or null	Your custom reference string.
`status`	string	One of: `CREATED`, `SENT`, `OPENED`, `VERIFIED`, `FAILED`, `EXPIRED`, `CANCELED`.
`failureReason`	string or null	Reason for failure (only set when status is `FAILED`).
`createdAt`	string (ISO 8601)	When the identity check was created.
`updatedAt`	string (ISO 8601)	When the identity check was last updated.
`organizationId`	string	The organization that owns the identity check.
`contactId`	string or null	Associated contact ID, if linked.

Contact Payload

Used by contact events (CONTACT_CREATED, CONTACT_UPDATED, CONTACT_DELETED).

{
  "id": "clx5mno...",
  "firstName": "Anna",
  "lastName": "Svensson",
  "email": "[email protected]",
  "phone": "+46701234567",
  "companyName": "Acme AB",
  "companyRole": "CEO",
  "externalId": "ext-456",
  "addressLine1": "Storgatan 1",
  "addressLine2": null,
  "city": "Stockholm",
  "state": null,
  "zipCode": "111 22",
  "country": "SE",
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:00:00.000Z",
  "organizationId": "clx2def...",
  "company": {
    "id": "clx6pqr...",
    "name": "Acme AB",
    "orgNumber": "5561234567",
    "country": "SE"
  }
}

Field	Type	Description
`id`	string	Contact ID.
`firstName`	string	First name.
`lastName`	string	Last name.
`email`	string or null	Email address.
`phone`	string or null	Phone number.
`companyName`	string or null	Company name (free text on the contact).
`companyRole`	string or null	Role at the company.
`externalId`	string or null	Your external ID for this contact.
`addressLine1`	string or null	Address line 1.
`addressLine2`	string or null	Address line 2.
`city`	string or null	City.
`state`	string or null	State/region.
`zipCode`	string or null	Zip/postal code.
`country`	string or null	Country code.
`createdAt`	string (ISO 8601)	When the contact was created.
`updatedAt`	string (ISO 8601)	When the contact was last updated.
`organizationId`	string	The organization that owns the contact.
`company`	object or null	Associated company (see below).

Company object:

Field	Type	Description
`id`	string	Company ID.
`name`	string or null	Company name.
`orgNumber`	string or null	Organization number.
`country`	string or null	Country code.

​Webhooks

​Setup

​Request Format

​Headers

​Verifying Requests

​Handling New Fields

​Delivery

​Events

​Document Events

​Party Events (per signer)

​Reminder Events

​Identity Check Events

​Contact Events

​Template Events

​Workspace Events

​Payloads

​Document Payload

​Document + Party Payload

​Identity Check Payload

​Contact Payload

​Next Steps

Managing Webhooks via API

Event Reference

Webhooks

Setup

Request Format

Headers

Verifying Requests

Handling New Fields

Delivery

Events

Document Events

Party Events (per signer)

Reminder Events

Identity Check Events

Contact Events

Template Events

Workspace Events

Payloads

Document Payload

Document + Party Payload

Identity Check Payload

Contact Payload

Next Steps