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_signed or document.party.signed events?
  • Why does sajn webhook verification fail, or why is X-Sajn-Signature sent instead of webhook-signature?
  • Why do Hookdeck retries of a sajn webhook fail verification after a few minutes?

Verification (core)

HeaderValue
webhook-idEvent ID, the same on every retry
webhook-timestampUnix seconds of this attempt
webhook-signatureOne 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

EventFires when
document.sentThe document is sent to its parties
document.fully_signedEvery party has signed (PDF not sealed yet)
document.completedsajn sealed the signed PDF: download it here
document.rejected / document.expiredA party rejects / a pending document expires
document.party.signedA party signs
document.party.delivery_failedAn invitation email bounces or SMS fails
approval_request.approvedThe last required approver approves
identity_check.verified / identity_check.failedAn identity check completes / fails
form.submittedA respondent submits a public form
webhook.testYou 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 2xx within 30 seconds; enqueue and process asynchronously. Missing headers or a bad signature: return 400.
  • Up to 12 attempts over about three days (6 s, 36 s, ~4 min, ~22 min, ~2 h, then 12 h each). 410 stops retries and pauses the endpoint; 429 honours Retry-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 compare createdAt before overwriting newer data.
  • No challenge request. When you save a webhook in the dashboard, sajn first POSTs an unsigned {"test": true}; your 400 JSON 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →