Webhook erklärt — HTTP-Callbacks für KI-Agenten und Messenger
Direkte Antwort: Ein Webhook ist ein HTTP-Endpoint, an den externe Dienste Events pushen, sobald etwas passiert. OpenClaw nutzt Webhooks z.B. für Telegram-Nachrichten oder GitHub-Events. Ohne Signatur-Validierung sind Webhooks ein Sicherheitsrisiko.
Was ist ein Webhook?
Ein Webhook ist ein HTTP-Endpoint auf deinem Server, den externe Dienste anrufen, wenn ein bestimmtes Event passiert. Statt dass dein Code regelmäßig nachfragt ("Gibt's was Neues?"), pusht der externe Dienst die Info aktiv zu dir, sobald sie verfügbar ist.
Beispiel: Wenn jemand deinem Telegram-Bot eine Nachricht schickt, sendet der Telegram-Server eine HTTP-POST-Anfrage an einen vorab konfigurierten Webhook-URL deines OpenClaw Gateways. Das Gateway empfängt die Nachricht und reagiert darauf.
Kontext
Webhooks sind seit etwa 2007 ein gängiges Pattern. Sie sind das Gegenteil von Polling: Statt alle X Sekunden zu fragen, ob es Updates gibt, sagt der externe Dienst Bescheid, sobald es welche gibt. Das spart Bandbreite, reduziert Latenz und ist generell effizienter.
In der OpenClaw-Welt begegnen dir Webhooks an mehreren Stellen:
- Telegram-Bot ruft das Gateway an, wenn neue Nachricht
- WhatsApp-Business-API postet Status-Updates
- GitHub-Skill empfängt Events bei Pushes
- Eigene Custom Skills, die externe Trigger empfangen
Polling vs. Webhook
| Aspekt | Polling | Webhook | | --- | --- | --- | | Initiator | Dein Code fragt | Externer Dienst pusht | | Latenz | Bis zum nächsten Poll | Sofort | | Ressourcen | Viele leere Calls | Nur bei Events | | Setup-Aufwand | Minimal | Endpoint öffentlich | | Sicherheit | Trivial (kein Endpoint) | Signatur-Validierung nötig |
OpenClaw kann beides. Telegram bietet z.B. sowohl Long-Polling als auch Webhooks. Bei kleinem Setup ist Polling oft einfacher (kein öffentlicher Endpoint), bei skalierendem Workload sind Webhooks effizienter.
Funktionsweise
Beim Webhook-Setup passieren typischerweise vier Schritte:
- Endpoint deklarieren: Du sagst dem externen Dienst, an welche URL er pushen soll
- Secret hinterlegen: Du teilst dem Dienst ein gemeinsames Geheimnis mit, mit dem er Anfragen signiert
- Eingehende POST-Requests verarbeiten: Dein Server nimmt die HTTP-Anfrage an, validiert die Signatur und verarbeitet das Event
- HTTP 200 zurückgeben: Schnelle Antwort, sonst retried der Dienst
Praxis-Beispiel
Ein simpler Telegram-Webhook-Setup:
# Webhook bei Telegram registrieren
curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
-d "url=https://my-server.example.com/webhook/telegram" \
-d "secret_token=$SHARED_SECRET"
Auf Server-Seite (Pseudo-Code im Express-Stil):
app.post('/webhook/telegram', (req, res) => {
// 1. Signatur validieren
const headerSecret = req.headers['x-telegram-bot-api-secret-token'];
if (headerSecret !== process.env.SHARED_SECRET) {
return res.status(401).send('Invalid secret');
}
// 2. Event verarbeiten
const update = req.body;
if (update.message) {
handleIncomingMessage(update.message);
}
// 3. Schnell antworten
res.status(200).send('OK');
});
Wichtig: Innerhalb von wenigen Sekunden antworten. Lange Verarbeitung (z.B. LLM-Call) gehört in einen Background-Job, nicht in den Webhook-Handler.
Webhook-Signaturen
Eine sichere Webhook-Implementierung validiert Signaturen. Verschiedene Dienste machen das unterschiedlich:
| Dienst | Header | Methode |
| --- | --- | --- |
| Telegram | X-Telegram-Bot-Api-Secret-Token | Plain Token Match |
| GitHub | X-Hub-Signature-256 | HMAC-SHA256 |
| Stripe | Stripe-Signature | HMAC-SHA256 + Timestamp |
| WhatsApp | X-Hub-Signature-256 | HMAC-SHA256 |
Bei HMAC-Signaturen rechnet der Server: HMAC(payload, secret) und vergleicht mit dem Header. Wenn nicht gleich, Anfrage verwerfen.
Sicherheits-Best-Practices
- Signatur immer validieren: Niemals einfach POST-Body verarbeiten ohne Auth
- HTTPS Pflicht: HTTP-Webhooks sind ein Sniffer-Paradies
- Idempotenz: Webhook-Dienste senden Events oft doppelt. Dedupliziere via Event-ID
- Rate-Limiting: Auch wenn Signatur passt, kann Brute-Force kommen. Limits einbauen
- Logs: Jede Webhook-Anfrage loggen (anonymisiert) für Debugging
- Timeout-Verhalten: Wenn dein Endpoint nicht in X Sekunden antwortet, retried der Dienst. Bei langer Verarbeitung schnell 200 zurück und Logik in Background-Queue
OpenClaw-Webhook-Endpoints
Wenn dein OpenClaw-Server Webhooks empfangen soll, brauchst du:
- Eine öffentliche URL (Domain mit HTTPS, z.B.
https://oc.example.com) - Einen Reverse-Proxy (nginx/Caddy), der den Webhook-Endpoint zum Gateway-Port routet
- SSL-Zertifikat (Caddy/Let's Encrypt automatisiert das)
- UFW muss Port 443 erlauben
Falls du keine Public-URL haben willst (kein Reverse-Proxy, kein offener Port): Tools wie ngrok oder Cloudflare Tunnels reichen die externen Webhook-Calls durch eine outbound-only Verbindung an deinen Server.
Häufige Fehler / Stolperfallen
- Signatur ignoriert: Reine Convenience kann teuer werden. Alle großen Webhook-Bypässe waren "wir validieren das nicht so genau".
- Webhook-Endpoint ohne Auth offen: Bots scannen das Internet. Ein offener
/webhook-Endpoint ist ein Spam-Magnet. - Lange Verarbeitung im Handler: Dienst retried nach Timeout, du verarbeitest Event zweimal. Schnelle 200 + async-Queue.
- Webhook-URL geheimhalten gedacht: Security through obscurity funktioniert nicht. URL kann geleaked werden, also die Signatur ist die echte Sicherheit.
- Lokaler dev ohne Tunnel: Lokaler Telegram-Bot-Test braucht eine öffentliche URL. ngrok ist dein Freund.
Verwandte Begriffe
Webhook-Setup für Telegram/WhatsApp: Modul 3 der Masterclass.