Webhook Grundlagen

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

Webhooks ermöglichen es Servern, Clients in Echtzeit über Ereignisse zu informieren, ohne dass der Client regelmäßig abfragen muss.

Kompakte Beschreibung

Webhooks sind HTTP-Callbacks, die ein Server an einen vom Client bereitgestellten Endpunkt sendet, wenn ein bestimmtes Ereignis eintritt. Sie werden genutzt, um über Zahlungen, Statusänderungen, Benachrichtigungen, Integrationen und viele weitere Ereignisse zu informieren. Im Gegensatz zur Polling-API, bei der der Client regelmäßig fragt, ob etwas Neues vorliegt, schiebt der Server mit Webhooks aktiv Daten an den Client. Eine gute Webhook-Implementierung berücksichtigt Sicherheit, Zuverlässigkeit, Idempotenz, Retry-Strategien und klare Fehlerbehandlung. Webhooks sind ein wichtiges Muster für ereignisbasierte Architekturen und moderne Integrationen zwischen Diensten.

Wichtige Komponenten

Ereignisquelle und Zielsystem

Die Ereignisquelle ist der Server, der das Webhook auslöst. Das Zielsystem ist der Client-Endpunkt, der das Webhook empfängt. Beide Systeme müssen über HTTP kommunizieren können, und das Zielsystem muss öffentlich erreichbar sein, falls der Server außerhalb des eigenen Netzwerks liegt.

Webhook URL registrieren

Der Client registriert eine URL bei der Ereignisquelle, an die Webhooks gesendet werden sollen. Diese URL wird oft über ein Dashboard oder eine API verwaltet. Es ist wichtig, dass die URL HTTPS verwendet und validiert wird, um Manipulationen zu vermeiden.

Payload und Event-Format

Der Payload ist der Inhalt des Webhooks, meist als JSON. Er enthält Informationen über das Ereignis, wie Event-Typ, Zeitstempel, betroffene Ressource und Details. Ein eindeutiges Event-ID Feld hilft, Duplikate zu erkennen.

Sicherheit und Signaturen

Webhooks sollten signiert werden, damit der Empfänger prüfen kann, dass die Nachricht tatsächlich von der erwarteten Quelle stammt. HMAC-SHA256 Signaturen über den Payload sind ein gängiges Verfahren. Der Empfänger verifiziert die Signatur mit einem gemeinsamen Geheimnis oder einem öffentlichen Schlüssel.

Idempotenz bei Webhooks

Webhooks können mehrfach gesendet werden, beispielsweise wegen Timeouts oder Wiederholungen. Der Empfänger muss Ereignisse anhand einer eindeutigen Event-ID idempotent verarbeiten. Gleiche Event-IDs sollten ignoriert oder verworfen werden, sobald sie bereits verarbeitet wurden.

Retry-Strategien

Wenn der Empfänger nicht mit einem Erfolgscode antwortet, sollte die Ereignisquelle das Webhook wiederholen. Wiederholungen sollten exponentiell zurückgehalten werden, um das Zielsystem nicht zu überlasten. Nach einer bestimmten Anzahl von Versuchen oder einem Zeitfenster sollte die Ereignisquelle aufgeben und das Ereignis als fehlgeschlagen markieren.

Erwartete Antwortcodes

Das Zielsystem sollte bei erfolgreichem Empfang mit 2xx antworten. 4xx Codes signalisieren, dass der Empfänger die Anfrage ablehnt oder nicht verarbeiten kann. 5xx Codes signalisieren ein vorübergehendes Problem, das eine Wiederholung rechtfertigt. Ein falscher Code kann dazu führen, dass Ereignisse fälschlicherweise wiederholt oder abgebrochen werden.

Timeouts

Die Ereignisquelle sollte einen Timeout definieren, nach dem sie die Anfrage als fehlgeschlagen betrachtet. Empfänger sollten Webhooks schnell bestätigen, längere Verarbeitungen asynchron im Hintergrund durchführen, um Timeouts zu vermeiden.

Webhook Logs und Monitoring

Beide Seiten sollten Webhooks loggen, inklusive Event-ID, Zeitstempel, HTTP-Statuscode und Antwortzeit. Monitoring hilft, Ausfälle, Verzögerungen und Fehlerhäufigkeiten zu erkennen. Dashboards für Zustellstatus sind besonders hilfreich.

Webhook Testing und Debugging

Für die Entwicklung eignen sich Tools wie ngrok, lokale Webhook-Tester oder Sandbox-Endpoints. Diese helfen, Webhooks lokal zu empfangen, zu inspizieren und zu debuggen, ohne öffentliche Server bereitstellen zu müssen.

Praxisbeispiel

Ein Payment-Dienst möchte seinen Kunden mitteilen, wenn eine Zahlung erfolgreich war. Der Kunde registriert eine Webhook-URL:

POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer token

{
  "url": "https://shop.example.com/webhooks/payments",
  "events": ["payment.succeeded", "payment.failed"]
}

Sobald eine Zahlung erfolgreich ist, sendet der Payment-Dienst ein Webhook:

POST /webhooks/payments
Content-Type: application/json
X-Event-ID: evt-9876543210abcdef
X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592

{
  "eventType": "payment.succeeded",
  "eventId": "evt-9876543210abcdef",
  "timestamp": "2026-07-01T12:34:56Z",
  "data": {
    "paymentId": "pay-123456",
    "orderId": "order-7890",
    "amount": 79.97,
    "currency": "EUR"
  }
}

Der Empfänger prüft die Signatur, speichert die Event-ID und verarbeitet die Zahlung. Er antwortet mit 200 OK, um die erfolgreiche Zustellung zu bestätigen. Bei einem Timeout oder 5xx Fehler wiederholt der Payment-Dienst das Senden nach exponentiellem Backoff.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: Webhook Grundlagen

Weiter im API Lernpfad

Der nächste Artikel im API Lernpfad behandelt GraphQL API Entwicklung: Schemas, Resolvers, Subscriptions und Apollo — die Alternative zu REST mit flexibler Datenabfrage und typisiertem Schema.

Quellen

1. https://web.dev/secure/signatures/
2. https://www.rfc-editor.org/rfc/rfc9110
3. https://ngrok.com/

Buchempfehlungen zur API-Entwicklung

Wenn Du Dich weiter mit Webhooks, API Design und Softwarearchitektur beschäftigen möchtest, empfehlen wir Dir die folgenden Bücher:

API-Entwicklung

Bücher über API-Design, REST, GraphQL, OpenAPI und API-Architektur

REST und HTTP: Entwicklung und Integration nach REST-Prinzipien von Stefan Tilkov

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

API-Design: Praxishandbuch für Java- und Webservice-Entwickler

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Microservices: Grundlagen flexibler Softwarearchitekturen von Eberhard Wolff

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert