Agent skill
sajn Webhooks Skill
Receive and verify sajn (sajn.se) e-signature webhooks. Use when setting up a sajn webhook endpoint, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature (Standard Webhooks) verification, or handling events like document.completed, document.fully_signed, document.party.signed, document.party.delivery_failed, document.rejected and identity_check.verified.
Install this skill
npx skills add hookdeck/webhook-skills --skill sajn-webhooks
sajn is a Swedish e-signature and identity-check platform. Its webhooks report document, party, approval, identity-check, contact, company, template, form, member, usage, security and sajn Login events per workspace. sajn signs every delivery with Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature).
API version requirement. Create the sajn webhook endpoint on API version 2026-10 or later. Endpoints on the deprecated 2026-09 version sign with X-Sajn-Signature instead of Standard Webhooks and fail verification.
When to Use This Skill
- How do I receive sajn webhooks?
- How do I verify a sajn webhook signature?
- Where do I find my sajn webhook signing secret (
whsec_...)? - How do I handle
document.completed,document.fully_signedordocument.party.signedevents? - Why does sajn webhook verification fail, or why is
X-Sajn-Signaturesent instead ofwebhook-signature? - Why do Hookdeck retries of a sajn webhook fail verification after a few minutes?
Verification (core)
| Header | Value |
|---|---|
webhook-id | Event ID, the same on every retry |
webhook-timestamp | Unix seconds of this attempt |
webhook-signature | One or more space-separated v1,<base64 HMAC-SHA256> entries |
Signed content is {webhook-id}.{webhook-timestamp}.{raw body}. The key is the base64-decoded part of the secret after whsec_. Verify with the standardwebhooks library (npm, PyPI), which compares every v1 entry in constant time:
const { Webhook } = require('standardwebhooks');
// rawBody: exact request body string, NOT re-serialised JSON
const prefix = req.get('webhook-id') ? 'webhook' : 'svix'; // fall back to svix-*
const event = new Webhook(process.env.SAJN_WEBHOOK_SECRET).verify(rawBody, {
'webhook-id': req.get(`${prefix}-id`),
'webhook-timestamp': req.get(`${prefix}-timestamp`),
'webhook-signature': req.get(`${prefix}-signature`),
}); // returns the parsed event; throws → respond 400
Python: from standardwebhooks.webhooks import Webhook, then Webhook(secret).verify(await request.body(), {...same three keys...}).
Timestamp window. The library always enforces a fixed 5-minute window. sajn re-signs each of its own retries with a fresh timestamp, but Hookdeck retries and replays resend the original timestamp, so the library rejects late retries after 5 minutes. A manual verifier (HMAC-SHA256 over {id}.{timestamp}.{raw body}, every v1, entry compared in constant time) where the window can be dropped or widened is in references/verification.md.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Event Envelope
{ "id": "cm4k2x9p10014abcd1234efgh", "type": "document.completed",
"createdAt": "2026-10-01T09:30:00.000Z", "apiVersion": "2026-10",
"workspaceId": "cm4k2x9p10001abcd1234efgh", "environment": "PRODUCTION",
"actor": null, "data": { "object": { "id": "cm4k2x9p10003abcd1234efgh", "status": "COMPLETED" } } }
The event type is the top-level type; data.object is the resource (some events add data.party, data.previousAttributes and similar). Dedupe on id (equal to webhook-id). Endpoints on 2026-09 instead send { event, payload, ... } with uppercase names such as DOCUMENT_COMPLETED.
Common Event Types
| Event | Fires when |
|---|---|
document.sent | The document is sent to its parties |
document.fully_signed | Every party has signed (PDF not sealed yet) |
document.completed | sajn sealed the signed PDF: download it here |
document.rejected / document.expired | A party rejects / a pending document expires |
document.party.signed | A party signs |
document.party.delivery_ | An invitation email bounces or SMS fails |
approval_ | The last required approver approves |
identity_check.verified / identity_check.failed | An identity check completes / fails |
form.submitted | A respondent submits a public form |
webhook.test | You call POST /api/v1/webhooks/{id}/test |
All 64 documented types (document, party, approval, identity check, contact, company, template, security, login and more): references/overview.md and sajn's event list.
Delivery Semantics
- Return a
2xxwithin 30 seconds; enqueue and process asynchronously. Missing headers or a bad signature: return400. - Up to 12 attempts over about three days (6 s, 36 s, ~4 min, ~22 min, ~2 h, then 12 h each).
410stops retries and pauses the endpoint;429honoursRetry-After; redirects are not followed. Endpoints failing for 72 hours (5+ failures in a row) are paused. - At least once and unordered: dedupe on
id, and comparecreatedAtbefore overwriting newer data. - No challenge request. When you save a webhook in the dashboard, sajn first POSTs an unsigned
{"test": true}; your400JSON answer passes that check.
Environment Variables
SAJN_WEBHOOK_SECRET=whsec_xxxxx # full whsec_ value; handlers fail closed (500) without it
sajn returns the secret only in the POST /api/v1/webhooks response and when you rotate it. One secret per endpoint and environment.
Local Development
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 sajn --path /webhooks/sajn
Create the webhook with the printed URL (on API version 2026-10), then call POST /api/v1/webhooks/{id}/test.
Reference Materials
- references/overview.md - Envelope, all event types, delivery and retries
- references/setup.md - Dashboard and API setup, API version, secret rotation, testing
- references/verification.md - Library and manual verification, timestamp window, debugging