Python Webhook Handlers — ELI5

Imagine you are waiting for a package. You have two choices: you can walk to your front door every five minutes and check if it arrived, or you can ask the delivery driver to ring your doorbell when they get there.

Checking every five minutes is exhausting and mostly pointless — the package is not there 99% of the time. The doorbell approach is smarter: you go about your day, and the driver lets you know the instant the package arrives.

Webhooks are the internet’s version of a doorbell.

Here is how they work: Say you run an online store, and you use Stripe to handle payments. When a customer pays, you need to know immediately so you can ship their order. Instead of your program asking Stripe every few seconds “Did anyone pay yet? How about now? Now?”, you give Stripe a special address (a URL) on your server and say: “When someone pays, ring this doorbell.”

Stripe remembers that address. The moment a payment goes through, Stripe sends a message to your address with all the details — who paid, how much, and for what. Your Python program receives this message and can immediately start processing the order.

That special address on your server is called a webhook endpoint, and the code that handles the incoming messages is called a webhook handler.

Webhooks are everywhere:

• GitHub rings your doorbell when someone pushes code to a project.
• Slack notifies your server when someone types a slash command.
• Shopify tells your system when a new order comes in.
• Twilio alerts you when someone sends a text message to your number.

The pattern is always the same: instead of constantly asking “Did anything happen?”, you set up a doorbell and wait for the ring.

One thing to remember: A webhook is a doorbell — instead of your program constantly checking for updates, the other service sends a message to your server the moment something happens.