Was sind Webhooks?

Ein Webhook ist ein automatischer HTTP-Callback: Tritt ein Ereignis ein, sendet ein System per POST einen Payload an eine URL, die ein anderes registriert hat. Der Begriff – 2007 als “benutzerdefinierte HTTP-Callbacks” geprägt – benennt die entscheidende Umkehrung: Statt dass Ihr System immer wieder fragt, ob sich etwas geändert hat, meldet das andere System es Ihrem in dem Moment, in dem es passiert. Es ist Push, gebaut aus den schlichtesten Teilen des Webs: einer HTTPS-URL, einem POST, einem JSON-Body und einer 2xx-Bestätigung.

Das Wichtigste in Kürze

Die Zustellung von Anfang bis Ende

SETUP     Empfänger stellt  https://api.example.com/hooks/payments bereit
          und registriert sie beim Anbieter, samt Ereignisauswahl + Geheimnis

EREIGNIS  Zahlung beim Anbieter erfolgreich

VERSAND   POST /hooks/payments
          webhook-id: evt_8fk2            ← Deduplizierungsschlüssel
          webhook-timestamp: 1767024900   ← Replay-Schutz (Teil der Signatur)
          webhook-signature: v1,d2Vio…    ← HMAC-SHA256(secret, id.timestamp.body)
          { "type": "charge.succeeded", "orderId": "o-1187" }

ACK       Empfänger prüft Signatur → 200 binnen Sekunden → Arbeit läuft asynchron
RETRY     kein 2xx? exponentielles Backoff über Stunden/Tage → Duplikate sind NORMAL

Beide Richtungen des Musters im Code – ein Daten-Trigger als Absender, eine Cloud Function als Empfänger und der Client, der nur das Ergebnis beobachtet:

// JavaScript — Cloud Code (cloud/main.js): both directions of a webhook
// OUTGOING: any data change can notify an external system
Parse.Cloud.afterSave('Order', async (req) => {
  if (req.object.get('status') !== 'paid') return;
  await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://hooks.example.com/orders', // the receiver's registered URL
    headers: { 'Content-Type': 'application/json' },
    body: { event: 'order.paid', id: req.object.id },
  });
});

// INCOMING: a Cloud Function is a ready-made webhook receiver
Parse.Cloud.define('paymentWebhook', async (req) => {
  verifySignature(req.params, process.env.WEBHOOK_SECRET); // HMAC first
  await markOrderPaid(req.params.orderId); // write fast, work async
  return { received: true }; // 2xx before heavy processing
});

// Flutter / Dart — Back4app Flutter SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
final orderQuery = QueryBuilder<ParseObject>(ParseObject('Order'))
  ..whereEqualTo('objectId', orderId);
final sub = await LiveQuery().client.subscribe(orderQuery);
sub.on(LiveQueryEvent.update, (order) {
  if (order.get<String>('status') == 'paid') showReceipt();
});
// The webhook itself was handled server-side — clients just watch the data.

// iOS / Swift — Back4app Swift SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
let orderQuery = Order.query("objectId" == orderId)
let sub = try await orderQuery.subscribe()
sub.handleEvent { _, event in
    if case .updated(let order) = event, order.status == "paid" {
        showReceipt()
    }
}
// The webhook itself was handled server-side — clients just watch the data.

// Android / Kotlin — Back4app Android SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
val orderQuery = ParseQuery.getQuery<ParseObject>("Order")
orderQuery.whereEqualTo("objectId", orderId)
val sub = ParseLiveQueryClient.Factory.getClient().subscribe(orderQuery)
sub.handleEvent(SubscriptionHandling.Event.UPDATE) { _, order ->
    if (order.getString("status") == "paid") showReceipt()
}
// The webhook itself was handled server-side — clients just watch the data.

Webhooks vs. APIs vs. Polling

Die Debatte ist weitgehend eine Scheindebatte: Ausgereifte Integrationen nutzen alle drei – Webhooks, um schnell von Änderungen zu erfahren, API-Aufrufe, um den maßgeblichen Zustand abzurufen und zu handeln, und einen langsamen Abgleichs-Poll als Netz unter dem Trapez.

Die Checkliste für Empfänger

Die Liste, die jede Anbieterdokumentation verstreut und keine Erklärung zusammenführt:

1. HMAC über den Rohdaten-Body prüfen – vor dem Parsen; neu serialisiertes JSON bricht Signaturen.
2. In konstanter Zeit vergleichen – String-Gleichheit verrät Timing-Informationen; nutzen Sie die Vergleichsfunktion Ihrer Krypto-Bibliothek.
3. Das Zeitstempelfenster durchsetzen – Zustellungen ablehnen, die älter als ~5 Minuten sind; weil der Zeitstempel Teil des signierten Inhalts ist, kann ein Angreifer eine gültig signierte alte Anfrage nicht mit frischer Uhrzeit erneut abspielen.
4. Schnell mit 2xx antworten – innerhalb von Sekunden, vor aufwendiger Arbeit; langsame Handler laufen in Timeouts und lösen Stürme doppelter Wiederholungsversuche aus.
5. Asynchron verarbeiten – in die Queue stellen, bestätigen, dann arbeiten.
6. Nach Ereignis-ID deduplizieren – mit einem Gedächtnis, das mindestens so lang ist wie das Wiederholungsfenster des Anbieters.
7. Dem Payload bei kritischen Aktionen nicht vertrauen – behandeln Sie den Webhook als Türklingel; rufen Sie den aktuellen Zustand über die API des Anbieters ab, bevor Sie Ware versenden oder Zugriff gewähren.
8. Zustellungen protokollieren und bei Fehlern alarmieren – Stille ist von einem defekten Endpoint nicht zu unterscheiden.

Ein Hinweis zur lokalen Entwicklung, den die Definitionsseiten auslassen: localhost ist aus dem Internet nicht erreichbar, daher läuft die Entwicklung über ein Tunneling-Tool, das Ihrem Rechner eine öffentliche URL leiht, plus ein Capture-Tool, um echte Payloads erneut abzuspielen.

Zustellsemantik, ehrlich betrachtet

Die Zustellung von Webhooks ist at-least-once: Der Anbieter wiederholt, bis die Bestätigung kommt, daher sind Duplikate ein Merkmal der Zuverlässigkeit, kein Fehler darin – Exactly-once-Zustellung über ein unzuverlässiges Netzwerk ist formal unmöglich, und das praktische Äquivalent ist at-least-once plus Ihr idempotenter Handler. Die Reihenfolge ist nicht garantiert: Wiederholungsversuche und parallele Sendungen verschränken sich, sodass updated vor created ankommen kann; wenden Sie Ereignisse nach ID und Version an oder rufen Sie den Zustand neu ab. Und Wiederholungsfenster enden: Ein Endpoint, der ein Wochenende lang ausfällt, kann Ereignisse endgültig verpassen – deshalb kombinieren kritische Integrationen, bei denen es um Geld geht, Webhooks mit regelmäßigem Abgleich, dieselbe At-least-once-Disziplin, die Broker formalisieren, nur über schlichtes HTTP. Dieser Vergleich lässt sich verallgemeinern: Ein Webhook ist Punkt-zu-Punkt-Push an eine bekannte URL; Pub/Sub ergänzt einen Broker, Topics und Fan-out; WebSockets und SSE bedienen Clients, keine Server. Webhooks sind genau dann die Antwort, wenn zwei Systeme ohne gemeinsame Infrastruktur von den Ereignissen des jeweils anderen erfahren müssen.

Die Absenderseite bauen

Webhooks zuverlässig zu versenden ist ein eigenes kleines System, und keine der gut rankenden Seiten skizziert es: eine Queue pro Ziel, damit ein toter Endpoint nicht alle anderen blockiert; Wiederholungsversuche mit exponentiellem Backoff und Jitter; ein Dead-Letter-Speicher mit Werkzeugen zur erneuten Zustellung, wenn die Versuche ausgeschöpft sind; HMAC-Signaturen mit Geheimnissen pro Endpoint und deren Rotation; Abonnements nach Ereignistyp, damit Empfänger nur wählen, was sie wollen; und Zustellprotokolle, die Ihre Kunden einsehen können, denn “Haben Sie es gesendet?” ist die erste Supportfrage. Ein Sicherheitspunkt, der nur Absender betrifft: Empfänger registrieren beliebige URLs, also prüfen Sie diese gegen interne Adressbereiche – ein Angreifer, der http://10.0.0.5/admin als seinen “Webhook-Endpoint” registriert, betreibt Server-Side Request Forgery, getarnt als Integrations-Feature.

Typische Anwendungsfälle

• Zahlungslebenszyklen – Abbuchungen, Erstattungen und Abo-Änderungen, die Ihrem Backend gemeldet werden, sobald sie abgeschlossen sind.
• CI/CD-Trigger – die klassische Verdrahtung, bei der ein Git-Push einen Build startet.
• App-übergreifende Automatisierung – Formular-Tools, Chat-Plattformen und CRMs, über die Ereignisse der jeweils anderen verkettet.
• Betriebliche Benachrichtigungen – Monitoring-Alarme und Lieferstatus, die in Team-Kanälen landen.
• Datensynchronisation – einen lokalen Spiegel eines Partnersystems aktuell halten, ohne dessen gesamte API zu pollen.

Sollten Sie einen Webhook verwenden? Eine Entscheidungsmatrix

Grenzen und Trade-offs

• Jenseits des Wiederholungsfensters ist die Zustellung Best Effort. Webhooks benachrichtigen; sie garantieren nichts. Abgleichs-Polls sichern alles ab, was nicht verloren gehen darf.
• Der Empfänger erbt die Pflicht zur Uptime. Die Verfügbarkeit Ihres Endpoints entscheidet nun über die Ereignisse eines anderen – Deployments, Cold Starts und Timeouts werden allesamt zu Integrationsfehlern.
• Sicherheit muss man aktiv einschalten. Ein Webhook-Endpoint ohne Prüfung ist eine nicht authentifizierte Schreib-API; die HMAC-Checkliste macht den Unterschied zwischen Integration und Injection.
• Debugging erstreckt sich über zwei Unternehmen. Zustellprotokolle auf beiden Seiten und Replay-Werkzeuge machen aus “Es ist nicht angekommen” statt einer Pattsituation einen Diff.
• Payloads verändern sich. Anbieter versionieren ihre Ereignisschemas; Konsumenten, die sich an exakte Strukturen binden, brechen unbemerkt – parsen Sie defensiv und ignorieren Sie unbekannte Felder.

Webhooks mit Back4app

Back4app ist eine Open-Source-Plattform für Backend as a Service (BaaS), die eine verwaltete Datenbank, automatisch generierte REST- und GraphQL-APIs, Authentifizierung, Dateispeicher und Serverless-Funktionen mit Cloud Code kombiniert. Beide Hälften des Musters sind nur ein Cloud-Code-Konstrukt entfernt, wie die Code-Tabs zeigen. Ausgehend: Ein afterSave-Trigger, der Ihre Daten beobachtet, ruft Parse.Cloud.httpRequest für jede registrierte URL auf – Ihre App wird zum Webhook-Anbieter, indem Sie die Funktion schreiben, und die Disziplinen der Absenderseite (Wiederholung bei Fehlern, Zustellungen protokollieren) leben in derselben Datei. Eingehend: Eine über HTTPS erreichbare Cloud Function ist ein fertiger Empfänger – HMAC gegen ein Geheimnis in der serverseitigen Konfiguration prüfen, das Ergebnis in die Datenbank schreiben, schnell antworten –, und die Änderung wird anschließend über Live Queries an jeden geöffneten Bildschirm verteilt. So schließt sich der Kreis vom Ereignis einer Zahlungsplattform bis zur Quittung beim Nutzer, ohne dass Sie an irgendeiner Stelle einen Server betreiben müssen.