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_KEYenvironment 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:
- Read
pauseReasonand fix the endpoint.HTTP_410means that your endpoint answered410 Gone.NETWORK_ERRORmeans that sajn got no response. - Reactivate the endpoint in Konsol, or call
POST /api/v1/webhooks/WEBHOOK_ID/reactivate. - Request
GET /api/v1/eventswithcreatedAfterset topausedAt, 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:
- Store the time of your last run as a watermark.
- Request events with
createdAfterset to the watermark minus a few minutes, and thetypefilter from the previous section. - Follow
nextCursoruntil it'snull, and handle each event. - 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
Was this page helpful?
Last updated on