What is a webhook

How it works

You give the service a URL and tell it which events you want. When one happens, the service sends an HTTP POST with the details, usually JSON. Your server reads it, does the work and answers 200. That is all a webhook is: an ordinary web endpoint that you did not call yourself.

@app.post("/hook")
def hook():
    if request.headers.get("X-Secret") != os.environ["HOOK_SECRET"]:
        abort(401)            # not from the service
    event = request.get_json()
    queue.put(event)          # do the slow work later
    return "", 200            # answer fast
$ curl -X POST https://you.example/hook -H "X-Secret: s3cret" -d '{"event":"paid"}'
HTTP/2 200

Three rules for a good receiver

The address must be public and, for most services, https. Telegram accepts ports 443, 80, 88 and 8443 and TLS 1.2 and up. On a laptop, a tunnel can expose it for tests; for real use the receiver lives on a server.

Do you need one?

What to know about sleep

• Polling bots: a bot on long polling only makes outgoing requests, and an outgoing request does not wake a sleeping computer. Switch such a bot to a webhook.
• The wake rule is confirmed for Telegram messages sent to your computer's webhook address. For other senders, test one event before you rely on it, and prefer senders that repeat a failed call.

Questions