Webhook
A webhook is an HTTP request that a service sends to a URL you choose when an event happens, so your system hears about it without asking over and over.
In plain words
There are two ways to learn that a contract was signed. You can ask the service every few minutes, which is called polling. Or the service can tell you the moment it happens. That second way is a webhook. You register a URL once, and the service posts a short message to it for each event.
An example
A staffing agency's system needs to know when a worker signs their agreement, so it can mark them cleared for a shift. It registers a webhook. When the worker signs, the agency's server receives a document.completed message within seconds, fetches the signed PDF and updates the worker's profile.
How it shows up in docuinked
Register a URL with create_webhook. The reply includes a secret, shown once. docuinked then posts events such as:
approval.requested, when an agent asks a person to approve a sendapproval.approved, when a person approves the exact draftsigner.signed, when one signer finishesdocument.completed, when everyone has signed and the PDF is sealed
The full list is on the webhooks page. Each message names the document and carries no document content. Fetch details with get_document.
Every delivery is signed with HMAC-SHA256 in a header. Check that signature against your secret before you act. Anyone can post to a public URL, so an unsigned message proves nothing.
Webhooks in workflows
In n8n, Make or Zapier, a webhook trigger node or step can receive these events and start the next step. The n8n page shows the setup. For agents, the same events tell a waiting job that a person approved or a signer finished. See workflows.
Common confusions
A webhook is not an API call you make. It flows the other way. The service calls you.
Webhooks can arrive more than once, or late. Networks fail and services retry. Make your handler safe to run twice for the same event ID. That is idempotency on the receiving side.
Related terms
- Idempotency
- Human-in-the-loop
- Embedded signing, whose browser events pair with webhooks
Common questions
What should my endpoint return?
Any 2xx status, as soon as you have checked the signature and stored the event. Do slow work in the background, so the reply isn't held up.
Can webhooks go to a localhost or private address?
No. docuinked only delivers to public https URLs on the default port, and refuses private network addresses. Use a public tunnel while you develop.
How many times does docuinked retry a failed delivery?
Up to 8 attempts, with a growing delay between them. A delivery counts as failed if your endpoint doesn't answer with a 2xx status within 30 seconds.
Related
Try it in test mode
Free during the beta. Test keys send no email, so you can build the whole flow first.