DEVELOPERS · WEBHOOKS
Webhooks
Seven document events, signed with the Standard Webhooks headers. Verify the raw body, then fetch the document.
webhook-id · webhook-timestamp · webhook-signature
documents.document.sent
documents.document.opened
documents.document.signed
documents.document.executed
documents.document.declined
documents.document.expired
documents.document.voided
A receiver
Four steps.
A DELIVERY CAN ARRIVE MORE THAN ONCE AND OUT OF ORDER. FETCH THE DOCUMENT; DO NOT TRUST THE EVENT AS THE LAST WORD.
Verify
Refuse a changed body, a wrong secret, an old timestamp.
import { verifyWebhook } from "@docustay/sdk";
const event = await verifyWebhook(process.env.DOCUSTAY_WEBHOOK_SECRET, req.headers, rawBody);Timestamps more than five minutes old are refused. Any Standard Webhooks library works with the secret (whsec_…).
Delivery you can debug.
Retries
A failed delivery is retried, and every attempt is in the delivery log.
Replay
Send again replays an event as often as you like, so you can fix the receiver without making another document.
Rotation
Rotate an endpoint's secret without recreating the endpoint.
Questions
Quick answers.
Can I send to localhost?
No. Endpoints must be public https addresses. Use a tunnel, or npx docustay listen --forward-to.
Does an event carry a signing link?
Never. Events carry facts about the document, not links or codes.
Which event means finished?
documents.document.executed: everyone signed and the sealed copy exists.