Webhook
Webhook
What is a webhook?
- The server notifies you first when an event occurs
- “Reverse API”
- Useful for real-time integration
Adding a webhook changes who does the work. With polling, our server hits the payment provider’s API every minute and asks, “Any new payments?” Even if it asks 1,440 times a day, it only catches a few dozen real events, and every other call is an empty lookup. Switch to webhooks and those wasted questions disappear, so the time from event to processing drops from minutes to seconds. The empty lookups that ate into your API call limits vanish entirely, and server costs and failure points shrink along with them.
Before you plug one in, cover four things: signature verification, response speed, retries, and idempotent handling. Most services attach an HMAC signature to the request header, so you need to check it against your secret key to filter out forged requests, and the receiver usually has to return 200 OK within 3 to 5 seconds. For heavy work such as inventory deduction or sending email, the standard approach is to put it in a queue and send the response first. If delivery fails, the provider resends several times at intervals of minutes to hours, so you must make sure an order is recorded only once even if the same event ID arrives twice.
Separating it from similar tools makes design easier. A regular API is a counter you visit when you need something, but a webhook is a one-time notice sent by the other side, so if you can’t process it the moment it arrives, it’s gone. If the goal is to update a screen in real time, SSE or WebSocket is the right fit, and if you need to queue hundreds of thousands of events a day in order, a message queue such as Kafka or SQS is the right fit. A webhook works best for delivering a few thousand events a day.
What breaks most often in the field is the belief that “a webhook arrives exactly once, in the order it was sent.” Because of retries and network conditions, the same payment confirmation can arrive twice, creating two orders and deducting inventory twice. It is also common for notifications that worked fine in development to stop arriving entirely in production because the receiving server sits behind a corporate firewall. Assume a webhook is a notification that is occasionally lost, and for events involving money, also run a daily ledger reconciliation (re-query) batch to catch anything missed overnight.
Seolyeong ParkGenerative AI and AX training expert with 17 years of hands-on experience and 200+ lectures, who gets non-specialists using AI right away
John KimJohn Kim, CEO of Nanum Consulting and author of “B2B Marketing Design”Jeff Lindsay coined the term in 2007. It became a widely used way to integrate web services by sending data automatically when an event occurs.
Let’s look at a hypothetical case: Company A, an online-store operator with 52 employees and KRW 18 billion (≈ US$13,467,000) in annual revenue. It checked payment completion with a batch job every 5 minutes, so it took an average of 7 minutes for an order to reach the warehouse, and customer service received 40 inquiries a week asking “I paid, so why is it still processing?” Four developers spent three weeks switching to payment webhooks.
- At the first meeting, Kim, the development team lead, summed it up: “Instead of asking every 5 minutes, let’s have the payment provider tell us first.” Then Kim registered the receiving URL in the payment gateway’s admin console.
- Lee, a backend developer, added HMAC signature verification and ran 20 test payments, confirming that 2 forged requests with mismatched signatures were blocked outright.
- On day two of operation, the same payment event arrived three times in a row and created duplicate orders. Assistant Manager Lee set event_id as a unique key in the database and changed the handler to return only 200 OK and ignore everything from the second delivery on.
- When responses ran past 6 seconds and the timeout failure rate climbed to 4%, the team moved inventory deduction and confirmation emails into a queue and changed the endpoint to respond as soon as a request is received, cutting the failure rate to 0.2%.
- Three weeks after the switch, the average time to a shipping order dropped from 7 minutes to 12 seconds, customer service inquiries fell from 40 to 6 a week, and polling calls went from 8,640 a day to zero.