What is a webhook? Explained for agent owners
An API is a door you knock on; a webhook is the service knocking on yours. How deliveries work, why receivers verify signatures, and which agent channels actually need a public URL.
A webhook is how one system tells another that something just happened. Instead of your code asking a service over and over whether there’s news (polling), you register a URL with the service, and the moment an event occurs it sends an HTTP POST (usually a JSON payload describing the event) to that URL. GitHub’s definition is as clean as any: webhooks “let you subscribe to events happening in a software system and automatically receive a delivery of data to your server whenever those events occur.”
The mechanics, end to end
Three moving parts. You (the receiver) run an endpoint, a URL that accepts POST requests. You register that URL with the sender and pick which events you care about. From then on, each matching event triggers one HTTP request from the sender to your URL, carrying the event as a payload plus headers identifying what kind of event it is. Your endpoint reads it, does whatever it does (updates a database, kicks off a build, pings a chat channel) and answers with a success status so the sender knows the delivery landed.
“Webhook vs API” in one line
An API is a door you knock on; a webhook is the service knocking on yours. Both are plain HTTP: the difference is purely who initiates. That flip is the whole value: in GitHub’s words, webhooks “require less effort and less resources than polling an API” and “allow near real-time updates, since webhooks are triggered when an event happens.” The two compose rather than compete: you’ll typically receive a webhook, then call the API back for details or follow-up actions.
The two catches
First: the sender has to be able to reach you, so a webhook receiver must be a publicly reachable HTTPS URL. Stripe’s docs state it as a flat requirement. That’s a real constraint if your software runs on a laptop or a private server; it’s why webhook setups so often involve tunnels and public endpoints where nothing else needed one. Second: a public URL accepts POSTs from anyone, not just the service you registered with. As Stripe puts it, without verification “an attacker could send fake webhook events to your endpoint.” The standard answer is signed deliveries: the sender includes a signature computed with a shared secret (GitHub’s X-Hub-Signature-256, Stripe’s Stripe-Signature), and your endpoint verifies it before believing a word of the payload.
Where an agent owner actually meets webhooks
Chat channels are the usual first encounter, and they split neatly on exactly the public-URL catch. OpenClaw’s Telegram channel uses long polling by default: the agent calls out to Telegram, so nothing needs to be reachable from the internet. Its Google Chat channel has no polling option: Google delivers messages by webhook only, so that channel is the one that forces a public HTTPS endpoint (the docs’ advice: expose only the webhook path, keep everything else private). OpenClaw’s Gateway can also expose its own inbound webhook endpoints so external systems can trigger your agent. Those endpoints are token-authenticated, and best kept behind loopback or a trusted proxy rather than raw on the internet. The pattern to carry away is the same in every case: a webhook is a door you’ve opened, so know which doors your setup has, and make each one check credentials before it believes what walks in.