# 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 send
- `approval.approved`, when a person approves the exact draft
- `signer.signed`, when one signer finishes
- `document.completed`, when everyone has signed and the PDF is sealed

The full list is on the [webhooks page](/docs/webhooks). 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](/integrations/n8n) shows the setup. For agents, the same events tell a waiting job that a person approved or a signer finished. See [workflows](/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](/glossary/idempotency) on the receiving side.

## Related terms

- [Idempotency](/glossary/idempotency)
- [Human-in-the-loop](/glossary/human-in-the-loop)
- [Embedded signing](/glossary/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.