In this post, you will learn what webhooks are and how to use one to send notifications from your scripts straight to your phone. Webhooks are one of the most common building blocks in software development, and once you understand them, a big part of modern automation stops being mysterious.

You have probably created an automation with Python before. Perhaps a script that sends an email, or something that scrapes data from a weather website. Now imagine the script crashed for some reason. You would not know immediately. You might come back days later and see that no data has been scraped for a week.

So what most people do is add a loop somewhere that keeps checking:

import time

while True:
    if check_if_done():
        break
    time.sleep(10)

This approach is called polling. Your script keeps asking “is it done yet?” over and over. It works, but think about what is actually happening here: your script sends thousands of requests a day just to hear “no” almost every time. It is like calling the pizza place every two minutes to ask if your order is ready. They will not enjoy that, and neither will the server you are polling.

The pizza place solves this differently, of course. You give them your number, and they call you when the order is ready. In software, that pattern is called a webhook.

A webhook is not a technology

So what is a webhook exactly? It is an HTTP request that someone else’s computer sends to a URL of your choice when an event happens. That is really the whole definition. It is not a library you install or a protocol you have to study. It is just an agreement between two computers: when X happens, send a POST request to this address.

Until now, you have always been the caller. Every requests.get() you have written is your script phoning a server. A webhook is the same thing in the opposite direction: the server phones you.

The script that texts you

Let me show you the fastest way to experience this. We will make a script send a notification to your phone.

The tool we will use is ntfy.sh. There is no signup, no API key, and no credit card involved. I have seen enough free services die under my projects to be careful with recommendations, but ntfy has been reliable for me.

First, install the ntfy app on your phone (free on iOS and Android) and subscribe to a topic. A topic is just a name you invent. Keep in mind that anyone who knows the name can send messages to it, so pick something hard to guess, like da-topic-4821, not test.

Then run this script:

import requests

requests.post(
    "https://ntfy.sh/da-topic-4821",
    data="Scraper finished. 340 rows."
)

About one second later, your phone buzzes.

That is four lines of Python, and your script can now reach you anywhere.

What actually traveled over the wire

Let’s look at what your script actually sent to ntfy’s server.

It is a verb (POST), an address, a couple of headers, and a body with the message. Every webhook in the world has this same shape. When Stripe informs an online shop that a payment succeeded, it sends this exact structure, just with a bigger JSON body. When GitHub tells a build server that someone pushed code, same thing.

The other side of the phone call

So far you have been the sender. Receiving a webhook is the reverse: you have a URL, and other computers send POST requests to it when something happens.

You might think you need Flask or FastAPI for this, but you don’t. Python comes with everything built in:

from http.server import HTTPServer, BaseHTTPRequestHandler

class Hook(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers["Content-Length"])
        body = self.rfile.read(length).decode()
        print("Webhook received:", body)
        self.send_response(200)
        self.end_headers()

HTTPServer(("", 8000), Hook).serve_forever()

Run this and you have a webhook receiver at http://localhost:8000. If you send it a POST request from a second terminal (reuse the four-line script from above and just change the URL), you will see the message printed. You just ran both sides of a webhook on one machine, with the standard library only.

By the way, if you want to watch a real webhook arrive before writing any code, open webhook.site in your browser. It gives you a temporary URL and shows every request that hits it, live. Five minutes there and webhooks will never feel mysterious again.

The catch: localhost is a private address

There is one thing that catches almost everyone at this point. Your receiver works when you send to it. However, if you paste http://localhost:8000 into Stripe’s webhook settings, nothing will ever arrive.

That is because localhost means “this machine”. It is a name only your own computer can hear. Your laptop has no public address on the internet. It sits behind your router, and the router has no idea it should forward anything to you.

There are two solutions. For testing, you can use a tunnel like ngrok, which gives you a temporary public URL that forwards to your laptop. For real applications, you deploy the receiver to a server, which is simply a computer with a public address that stays on. That trip from laptop to server is a topic we will keep coming back to in this publication.

The pattern to steal today

Here is what I recommend you do with all this. Wrap the sender in a small function and keep it in every project:

import requests

def notify(message):
    requests.post("https://ntfy.sh/da-topic-4821", data=message)

notify("Backup complete: 2.3 GB")
notify(f"Script crashed: {error}")
notify("Price dropped below 40 EUR")

My personal rule is that any script running longer than a coffee gets a notify() call at the end and one in the error handler. It changes how you work, because your scripts stop being things you watch and start being things that report to you.

And once you know the shape, you will notice webhooks everywhere: GitHub triggering tests, Stripe unlocking accounts, Telegram bots replying to messages.

In a future post, we will take the next step: giving your own function a public URL, so that anything on the internet can call your code.

-Ardit