# sajn Webhooks

[sajn](https://sajn.se) 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)

| 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:

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/sajn-webhooks/references/verification.md).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sajn-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sajn-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sajn-webhooks/examples/fastapi/).

## Event Envelope

```json
{ "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_failed` | An invitation email bounces or SMS fails |
| `approval_request.approved` | 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/sajn-webhooks/references/overview.md) and [sajn's event list](https://docs.sajn.se/webhooks/events).

## 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

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/sajn-webhooks/references/overview.md) - Envelope, all event types, delivery and retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sajn-webhooks/references/setup.md) - Dashboard and API setup, API version, secret rotation, testing
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sajn-webhooks/references/verification.md) - Library and manual verification, timestamp window, debugging