Kurzfassung
Ein Webhook ist ein „umgekehrter“ API-Aufruf: Statt den Dienst zu fragen „ist etwas passiert?“, sendet der Dienst bei einem Ereignis einen HTTP-POST an Ihre URL. So entfällt Polling und Sie sparen Ressourcen. Ideal für Zahlungen, Benachrichtigungen und Synchronisation.
Für wen ist das
- Entwickler, die externe APIs integrieren (Zahlung, CRM, Shops)
- Architekten event-basierter Systeme
- Alle, die Automatisierungen bauen (z. B. Zapier, n8n, eigener Backend)
Keyword (SEO)
webhook was ist, webhooks api, webhook integration, event callback api
Webhook vs Polling
| Polling | Webhook |
|---|---|
| Sie fragen alle X Sekunden: „Neue Daten?“ | Der Dienst sendet Ihnen einen Request, wenn etwas passiert |
| Mehr Requests, Latenz | Weniger Requests, nahezu sofortige Reaktion |
| Einfacher beim Dienst | Erfordert Endpoint auf Ihrer Seite |
Webhook = Callback-URL, die Sie dem Dienst nennen. Bei einem Ereignis (z. B. Zahlung, Statusänderung) sendet der Dienst einen POST an diese URL mit Payload.
Wann Webhooks nutzen?
- ✅ Zahlungen (Stripe etc. – „Zahlung bestätigt“)
- ✅ Änderungen in externem System (Bestellung, Lead, Ticket)
- ✅ Benachrichtigungen (E-Mail zugestellt, SMS gesendet)
- ✅ Sync (Produktkatalog, Preise)
- ❌ Wenn Sie keine öffentliche URL haben (localhost) – in der Entwicklung Tunnels nutzen (ngrok, cloudflared)
Wie sieht es beim Empfänger aus?
1. URL registrieren
Im API-Dashboard (z. B. Stripe) tragen Sie ein: https://ihre-domain.de/api/webhooks/stripe.
2. Request empfangen
Der Dienst sendet einen POST mit Body (JSON) und oft einem Signatur-Header (z. B. Stripe-Signature).
3. Verifikation
Immer die Signatur (HMAC) prüfen, damit sich niemand als der Dienst ausgeben kann:
// Beispiel: Stripe
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET);
4. Idempotenz
Dasselbe Event kann zweimal ankommen (Retry). event.id (oder ähnlich) nutzen und verarbeitete IDs speichern – bei Duplikat 200 zurückgeben und nichts tun.
5. Schnell mit 2xx antworten
Innerhalb weniger Sekunden 200 zurückgeben. Schwere Verarbeitung im Hintergrund (Queue, Job). Der Dienst macht bei Timeout oder 4xx/5xx einen Retry.
Best Practices
- HTTPS – Pflicht
- Signaturverifikation – ohne Ausnahme
- Idempotenz – Retries berücksichtigen
- Logging – Raw Body für Debugging, keine sensiblen Daten im Klartext
- Timeout – Dienste erlauben meist 5–30 s; wenn länger – 200 zurückgeben und asynchron verarbeiten
FAQ
Was, wenn mein Endpoint kurz nicht erreichbar ist?
Der Dienst macht in der Regel Retries (z. B. mit exponential backoff). Nach mehreren Fehlern gibt es oft ein „failed deliveries“-Panel oder Logs beim Dienst.
Gehen Webhooks auf localhost?
Nicht direkt. Tunnel nutzen: ngrok, cloudflared, localtunnel – sie stellen eine öffentliche URL auf Ihren localhost bereit.
Webhook vs WebSocket?
Webhook = ein Request pro Event (zustandslos). WebSocket = dauerhafte Verbindung, Strom von Events. Webhooks sind für die Integration mit externen Anbietern einfacher.