Webhook
Definition
A webhook inverts the usual direction of a REST API call. You register an endpoint, meaning a URL on a server you control, and choose which events should reach it. When one of them occurs the service POSTs a JSON body describing it: the event type, a timestamp, an identifier and the relevant data. Your endpoint is expected to answer quickly, normally with a 200, and to do any slow work afterwards. Most services sign the request with a shared secret carried in a header, so you can confirm it really came from them, and most retry on an increasing delay if your endpoint is down or sluggish. The pattern is sometimes called a reverse API or an HTTP callback.
Why It Matters
Polling wastes both time and requests. Asking every minute whether an upload has finished means fifty-nine pointless calls an hour and up to sixty seconds of lag; a webhook lands in under a second and costs one request. The delivery guarantee is weaker, though, and that is the part people miss. A webhook can arrive twice, arrive out of order, or never arrive at all if your endpoint was down for the whole retry window. Handlers therefore have to be idempotent — processing the same event twice must leave the same result — because the alternative is a duplicate delivery sending a second invoice.
How It Works
You give the service an HTTPS URL and it stores that against your account. On an event it builds a JSON payload, computes a signature over the raw body using your secret, places it in a header such as X-Signature, and posts the lot. Your handler reads the raw body before parsing anything, recomputes the signature and rejects the request when it does not match, which is what stops someone who guesses the URL from forging events. It then returns 200 straight away and queues the real work for later. Anything other than a success code counts as a failure, and the service retries on a backoff schedule that often runs for hours.
Real-World Example
A team generates documentation pages from an assistant and publishes them through an API. A webhook fires on each successful publish and posts the new address, say handbook.99helpers.site, into a chat channel with the version number beside it. A static host cannot run the receiving endpoint itself, so the handler lives on a small serverless function elsewhere: the host serves the pages, the function does the talking. Nobody has to remember to announce a release again.
Common Mistakes
- ✕Skipping signature verification because the URL is hard to guess — an unverified endpoint accepts events from anyone who finds it
- ✕Doing the work before replying, so a slow handler times out and the service retries an action that already ran
- ✕Assuming exactly-once delivery; store the event identifier and ignore repeats, or you will process the same thing twice
Related Terms
REST API
A way of exposing a service over HTTP where each thing you can act on has its own URL, and the HTTP method says what you are doing to it. GET reads, POST creates, PUT replaces, DELETE removes.
API Token
A secret string that identifies your account to an API in place of a username and password. You send it with each request, and the service checks it and applies whatever permissions it carries.
HTTP Status Code
An HTTP status code is the three-digit number a server returns at the head of every response, saying what happened to the request. It is the first thing on the first line — a 200 means here is the file, a 404 means there is nothing at that address.
Serverless
A hosting model where you deploy a function rather than a machine, and the provider starts it on demand and charges for the time it ran. There are still servers — you simply do not choose, patch or keep them.
MCP Server
A program that exposes a set of tools to an AI assistant over the Model Context Protocol. The assistant sees a list of actions it can take — read this, create that — and calls them during a conversation.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →