Skip to Content
Documents

Wait for signatures without polling

Learn when a document is signed from the document.completed webhook, catch up on missed events with GET /api/v1/events, and recover when sajn pauses your webhook

In this guide, you find out when a sent document is signed without polling it. A webhook tells you the moment the sealed PDF is ready, a scheduled read of GET /api/v1/events catches anything the webhook missed, and the same read keeps you current if sajn pauses your webhook.

Before you begin

  • Store your API key in the SAJN_API_KEY environment variable.
  • Have an HTTPS endpoint that sajn can reach. If you can't expose one, see Without a webhook endpoint.

Don't poll each document

A loop that calls GET /api/v1/documents/DOCUMENT_ID every few seconds until the status changes spends your rate limit on requests that return nothing new. A document stays PENDING until every party signs, a party rejects it, or it expires or is withdrawn. If nobody acts, that can take months, and the loop never stops: a poll every 2 minutes on one forgotten document makes 1,440 requests a day. The limit is shared by every API key and integration in your organization, so a busy poll can slow down the rest of your integration. One integration went from about 7,000 requests a day to fewer than 100 when it replaced polling with the steps below.

Get notified when a document is signed

Subscribe to the end states

Create a webhook for the events that end a document's signing:

curl -X POST https://app.sajn.se/api/v1/webhooks \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/sajn",
    "events": [
      "document.completed",
      "document.rejected",
      "document.expired",
      "document.withdrawn"
    ],
    "apiVersion": "2026-10"
  }'

Store the secret from the response. To check each party's progress as well, add document.party.signed. For every option, see Manage webhook endpoints.

Download the signed PDF on document.completed

sajn fires document.completed after it has sealed the signed PDF, so SIGNED is ready when the event arrives. document.fully_signed fires earlier, before the seal. Don't download the signed file on it.

The event's data.object is the document. Verify the delivery's signature, answer 2xx right away, and then download the files. For a complete handler, see Archive documents when they're completed.

Catch up with GET /api/v1/events

A webhook delivery can fail while your endpoint is down. Once an hour, read the events since your last run and pass each one to the same handler:

curl "https://app.sajn.se/api/v1/events?createdAfter=2026-11-09T08:00:00Z&type=document.completed,document.rejected,document.expired,document.withdrawn&limit=100" \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10"

Each event has the same shape as a webhook delivery, and its id stays the same, so a handler that skips IDs it has seen processes each event once. The list reaches back 30 days. For the full loop with a watermark and paging, see Reconcile on a schedule.

Recover when sajn pauses your webhook

sajn pauses an endpoint that answers 410 Gone, or that has failed every attempt for 72 hours. A paused endpoint gets no deliveries until you reactivate it, and reactivating doesn't resend the events from the pause. A paused webhook is a broken endpoint to fix. Don't replace it with polling: the hourly read of GET /api/v1/events already keeps your data current while the endpoint is paused.

To find out about a pause, set failureNotificationEmail to an address that someone reads:

curl -X PATCH https://app.sajn.se/api/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  -H "Content-Type: application/json" \
  -d '{ "failureNotificationEmail": "ops@example.com" }'

Your hourly catch-up job can also read GET /api/v1/webhooks/WEBHOOK_ID and raise an alert when status is PAUSED.

When sajn pauses your endpoint, do the following:

  1. Read pauseReason and fix the endpoint. HTTP_410 means that your endpoint answered 410 Gone. NETWORK_ERROR means that sajn got no response.
  2. Reactivate the endpoint in Konsol, or call POST /api/v1/webhooks/WEBHOOK_ID/reactivate.
  3. Request GET /api/v1/events with createdAfter set to pausedAt, and pass each event to your handler. Your handler skips the events that it has already processed, so this step is safe after the hourly job has run.

Without a webhook endpoint

If sajn can't reach your server, read GET /api/v1/events on a schedule instead of polling each document. One request returns every document that finished since the last run, however many documents you have out for signing:

  1. Store the time of your last run as a watermark.
  2. Request events with createdAfter set to the watermark minus a few minutes, and the type filter from the previous section.
  3. Follow nextCursor until it's null, and handle each event.
  4. Store the time when this run started as the new watermark.

Every few minutes is enough for most integrations.

Wait for the original PDF

A draft has no ORIGINAL file. sajn generates it in the background when you send the document, and it's ready when document.sent fires. For a QES document, and for some documents where a party picks products, sajn generates it after the parties have filled in their fields. Until then, GET /api/v1/documents/DOCUMENT_ID/files/ORIGINAL returns 409 INVALID_STATE, and GET /api/v1/documents/DOCUMENT_ID/files leaves it out.

Next steps

Webhook events

See every event and when it fires.

Replay and reconcile events

Read past events and retry deliveries.

Download documents

Download the sealed PDF, the original, and the journal.

Rate limits

See your limit and how to handle 429.

Was this page helpful?

Last updated on