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.

Verifying Requests

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

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.

Party Events (per signer)

These events fire when a specific signer 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.

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.

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",
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:00:00.000Z",
  "organizationId": "clx2def...",
  "status": "COMPLETED",
  "signers": [
    {
      "id": "clx3ghi...",
      "name": "Anna Svensson",
      "email": "anna@example.com",
      "signingStatus": "SIGNED"
    }
  ]
}

Field	Type	Description
`id`	string	Document ID.
`title`	string	Document title.
`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`.
`signers`	array	List of signers (see below).

Signer object:

Field	Type	Description
`id`	string	Signer ID.
`name`	string	Signer’s name.
`email`	string	Signer’s email address.
`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 signer that triggered the event.

{
  "document": {
    "id": "clx1abc...",
    "title": "Employment Agreement",
    "createdAt": "2026-04-16T10:00:00.000Z",
    "updatedAt": "2026-04-16T12:00:00.000Z",
    "organizationId": "clx2def...",
    "status": "PENDING",
    "signers": [...]
  },
  "party": {
    "id": "clx3ghi...",
    "name": "Anna Svensson",
    "email": "anna@example.com",
    "signingStatus": "SIGNED"
  }
}

Field	Type	Description
`document`	object	The full Document payload.
`party`	object	The signer that triggered this event (same shape as a signer 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": "erik@example.com",
  "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` or `SMS`.
`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": "anna@example.com",
  "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

Webhooks

Setup

Request Format

Headers

Verifying Requests

Delivery

Events

Document Events

Party Events (per signer)

Reminder Events

Identity Check Events

Contact Events

Payloads

Document Payload

Document + Party Payload

Identity Check Payload

Contact Payload

Next Steps

Managing Webhooks via API

Event Reference

Documentation Index

​Webhooks

​Setup

​Request Format

​Headers

​Verifying Requests

​Delivery

​Events

​Document Events

​Party Events (per signer)

​Reminder Events

​Identity Check Events

​Contact 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

Delivery

Events

Document Events

Party Events (per signer)

Reminder Events

Identity Check Events

Contact Events

Payloads

Document Payload

Document + Party Payload

Identity Check Payload

Contact Payload

Next Steps