What is a webhook, explained simply?

What it actually is

A webhook is a URL you hand to another service so it can tell you the instant something happens, instead of you asking over and over. Picture the difference between calling a restaurant every ten minutes to ask “is my table ready?” and just giving them your phone number so they text you the moment it opens up. The restaurant is the sender, your phone number is the webhook, and the text is the “event,” a small package of information sent as an HTTP request the second the thing occurs. No app-to-app polling, no wasted requests. Just a message that arrives on someone else’s schedule, not yours.

Why your AI just did this

Your agent reaches for a webhook whenever your app needs to react to something happening outside your own code: a customer pays through Stripe, a user signs up through Clerk, a file finishes processing, a push to GitHub should trigger a deploy, an email bounces through Resend. Instead of writing code that checks “did the payment go through yet?” every few seconds, the agent registers a URL (often something like /api/webhooks/stripe) with that outside service, and the service calls it the moment the real event happens. That’s why you’ll see your agent scaffold a new API route with a name like that, plus code that reads the raw request body and checks a signature before doing anything with the data inside it.

When you’ll run into it

You’ll see it most directly in a provider’s dashboard (Stripe, Clerk, GitHub, Resend) on a screen called something like “Webhooks” or “Add endpoint,” which asks for a URL and hands you a signing secret to copy somewhere safe. Locally is where it gets awkward: your dev server runs on localhost, and the public internet can’t reach localhost, so webhook calls just never arrive. That’s when your agent might set up a tunneling tool like ngrok, or a provider’s own CLI (Stripe’s stripe listen, for instance) to forward real events to your machine while you test. You’ll also meet webhooks in failure logs: a dashboard showing failed deliveries with a 400 or 401 status, usually because the signature check failed or your endpoint took too long and the provider gave up.

What to check

• The endpoint verifies the request’s signature against a secret before trusting anything in it. A public URL can be POSTed to by anyone, and an unverified webhook will happily process fake events
• The signing secret lives in an environment variable, not hardcoded in the route file
• The endpoint responds quickly with a success status even if the real processing happens after. Most providers retry aggressively if they don’t get a fast response
• The handler is idempotent. The same event can legitimately arrive twice (retries happen), so processing it twice shouldn’t double-charge someone or send two emails
• You’ve sent a test event from the provider’s dashboard or CLI before relying on the real flow to prove itself in production

Say it like a dev

Instead of: “Make it check every few seconds if the payment worked.” Say: “Set up a webhook so Stripe tells us the moment the payment succeeds.”

Instead of: “Why isn’t anything happening when I test this on my computer?” Say: “Localhost isn’t reachable from the internet. Can you set up a tunnel so the webhook can reach my dev server?”

Instead of: “Just trust whatever hits that URL.” Say: “Make sure the webhook handler verifies the signature before it processes anything.”