Skip to Content
Webhooks

Create a new webhook

POST
/api/v1/webhooks

Create a new webhook subscription for your workspace.

Required Fields:

  • url - URL that receives a POST request for each event
  • events - The event types to subscribe to, such as document.completed

Optional Fields:

  • secret - Signing secret in the Standard Webhooks format, whsec_<base64>. sajn generates one when omitted, and the response returns it once
  • enabled - Whether the webhook is active (default: true)
  • apiVersion - API version, such as 2026-10, that determines the body this endpoint receives. Defaults to the API version of this request. The endpoint keeps this version until you change it with PATCH /api/v1/webhooks/:id

Delivery: each event is a POST with the body { id, type, createdAt, apiVersion, workspaceId, environment, actor, data }, the same object GET /api/v1/events/:id returns. data.object is the resource the event is about. The request follows Standard Webhooks: webhook-id is the event id, webhook-timestamp is the send time in Unix seconds, and webhook-signature is v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<raw body>, keyed with the base64-decoded secret after whsec_. Any Standard Webhooks library verifies it. Return a 2xx status code within 30 seconds. sajn retries any other answer, a timeout, and a network error with backoff for about three days, and stops at once on 410 Gone. Delivery is at least once, so deduplicate on webhook-id.

Event types: events takes the following values:

  • Document, with the document in data.object: document.created (with data.source), document.sent, document.fully_signed, document.completed, document.rejected, document.expired, document.withdrawn, document.updated, document.deleted, document.restored, document.archived, document.unarchived, document.expiration_extended, document.expiring_soon, and document.comment.created, with the comment in data.object
  • Party, with the document in data.object and the party in data.party: document.party.sent, document.party.delivery_failed, document.party.opened, document.party.read, document.party.signed, document.party.rejected, document.party.delegated, document.party.auth_failed, document.party.verified, document.party.updated, document.party.added, document.party.removed, document.party.reminded
  • Bundle, with the bundle in data.object: bundle.sent, bundle.party.signed, bundle.completed, bundle.cancelled
  • Archive import, with the import in data.object: archive_import.completed, once per run, and archive_import.undone
  • Approval: approval_request.created, approval_request.approved, approval_request.rejected, approval_request.cancelled
  • Identity check: identity_check.created, identity_check.sent, identity_check.opened, identity_check.verified, identity_check.failed, identity_check.cancelled
  • Contact, company and template: contact.created, contact.updated, contact.deleted, company.created, company.updated, company.deleted, template.created, template.updated, template.deleted, template.restored
  • Form: form.submitted, with the same fields as GET /api/v1/forms/:id/submissions/:submissionId
  • Workspace: workspace.created, member.added, member.invited, member.invite_accepted
  • sajn Login: login.completed, login.failed, with the login session in data.object
  • Security, a feed for a SIEM: security.document_downloaded, security.documents_exported, security.signature_identity_accessed, security.member_removed, security.member_role_changed, security.role_updated, security.workspace_retention_updated
  • Usage: usage.limit_reached

Plan Requirement: Requires the Team plan or higher, or a sandbox organization.

Authorization

headerAuthorizationBearer <token>

API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.

Header Parameters

Sajn-Version?string

API version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.

Value in"2026-09""2026-10"
Sajn-Workspace?string

ID of the workspace this request acts in, from GET /api/v1/workspaces. Without it, an API key acts in its default workspace. The token's user must be a member of the workspace; an OAuth token only accepts the workspace it was granted for. A workspace that doesn't exist or can't be reached returns 403 WORKSPACE_ACCESS_DENIED.

Idempotency-Key?string

Makes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.

Lengthlength <= 255

Request Body

Body

application/json
  1. body

Create webhook request

url*string

URL that will receive webhook events

Formaturi
events*array<>

The event types to subscribe to, such as document.completed

Items1 <= items
secret?|

Signing secret for this endpoint, in the Standard Webhooks format: whsec_ followed by the base64 of 24 to 64 random bytes. Omit it to have sajn generate one

enabled?boolean

Whether this webhook is active (default: true)

Defaulttrue
failureNotificationEmail?|

Email address that will be notified if webhook delivery fails

Match^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
apiVersion?string

API version that determines the payload shape this endpoint receives. Defaults to your organization's API version

Value in"2026-09""2026-10"

Response Body

Webhook response

application/json
  1. response

Webhook response

id*string

Unique webhook identifier

url*string

URL that receives webhook events

secret?string

Signing secret for this endpoint, in the Standard Webhooks format whsec_<base64>. Returned only when you create the webhook and when you rotate the secret, so store it then.

enabled*boolean

Whether this webhook is active

status*string

DISABLED when enabled is false. PAUSED when sajn stopped delivering because the endpoint failed for three days or answered 410 Gone; resume with POST /api/v1/webhooks/:id/reactivate.

Value in"ENABLED""DISABLED""PAUSED"
pausedAt*|

When sajn paused the webhook. Null unless status is PAUSED.

Formatdate-time
pauseReason*|

Why sajn paused the webhook: HTTP_<status code> for the last answer, such as HTTP_410, or NETWORK_ERROR. Null unless status is PAUSED.

failureNotificationEmail*|

Email address that receives a notification if webhook delivery fails

events*array<>

The event types this webhook subscribes to

apiVersion*string

API version, in YYYY-MM format, that determines the payload shape this endpoint receives

createdAt*string

Date and time when webhook was created

Formatdate-time
updatedAt*string

Date and time when webhook was last updated

Formatdate-time
Example Request
curl -X POST 'https://app.sajn.se/api/v1/webhooks' \  -H 'Content-Type: application/json' \  -d '{  "url": "https://example.com/webhooks/sajn",  "events": [    "document.fully_signed",    "document.completed"  ],  "failureNotificationEmail": "dev@example.com",  "apiVersion": "2026-10"}'
Example Response
{  "id": "cm4k2x9p10013abcd1234efgh",  "url": "https://example.com/webhooks/sajn",  "enabled": true,  "status": "ENABLED",  "pausedAt": null,  "pauseReason": null,  "failureNotificationEmail": "dev@example.com",  "events": [    "document.fully_signed",    "document.completed"  ],  "apiVersion": "2026-10",  "createdAt": "2026-09-01T12:00:00.000Z",  "updatedAt": "2026-09-01T12:00:00.000Z",  "secret": "whsec_c2Fqbi1leGFtcGxlLXdlYmhvb2stc2VjcmV0LTAwNDI="}

Was this page helpful?