Create a new webhook
Create a new webhook subscription for your workspace.
Required Fields:
url- URL that receives a POST request for each eventevents- The event types to subscribe to, such asdocument.completed
Optional Fields:
secret- Signing secret in the Standard Webhooks format,whsec_<base64>. sajn generates one when omitted, and the response returns it onceenabled- Whether the webhook is active (default: true)apiVersion- API version, such as2026-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 withPATCH /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(withdata.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, anddocument.comment.created, with the comment indata.object - Party, with the document in
data.objectand the party indata.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, andarchive_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 asGET /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 indata.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.
AuthorizationBearer <token>API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.
Sajn-Version?stringAPI 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.
"2026-09""2026-10"Sajn-Workspace?stringID 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?stringMakes 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.
length <= 255Body
application/json- body
Create webhook request
url*stringURL that will receive webhook events
urievents*array<>The event types to subscribe to, such as document.completed
1 <= itemssecret?|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?booleanWhether this webhook is active (default: true)
truefailureNotificationEmail?|Email address that will be notified if webhook delivery fails
^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$emailapiVersion?stringAPI version that determines the payload shape this endpoint receives. Defaults to your organization's API version
"2026-09""2026-10"Webhook response
application/json- response
Webhook response
id*stringUnique webhook identifier
url*stringURL that receives webhook events
secret?stringSigning 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*booleanWhether this webhook is active
status*stringDISABLED 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.
"ENABLED""DISABLED""PAUSED"pausedAt*|When sajn paused the webhook. Null unless status is PAUSED.
date-timepauseReason*|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*stringAPI version, in YYYY-MM format, that determines the payload shape this endpoint receives
createdAt*stringDate and time when webhook was created
date-timeupdatedAt*stringDate and time when webhook was last updated
date-timecurl -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"}'{ "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?