Webhooks

#Definition

Webhooks drehen das klassische API-Modell um. Statt dass deine Anwendung in festen Intervallen beim Anbieter nach neuen Daten fragt, schickt der Anbieter aktiv eine Nachricht, sobald etwas passiert. Du registrierst einen Endpunkt wie https://api.deinunternehmen.de/webhooks/orderbird beim Sender. Sobald ein Ereignis wie "Bestellung abgeschlossen" eintritt, schickt der Sender einen POST-Request mit dem Payload an deinen Endpunkt.

Das Modell heißt Push-Pattern, im Gegensatz zum Pull-Pattern einer klassischen REST-Abfrage. Push ist schneller, weil die Verzögerung von der Datenerzeugung bis zur Verarbeitung im Sekundenbereich liegt. Pull ist robuster, weil dein System auch bei kurzen Webhook-Ausfällen die Daten noch nachträglich abholen kann. In einer reifen Integration setzt du beide Muster ein, eng verzahnt mit einer offenen API und der POS-Schnittstelle.

#Anwendung in Gastro-Software

Typische Webhook-Events in der Gastronomie sind Bestellung-erstellt, Bestellung-abgeschlossen, Storno-ausgelöst, Rechnung-bezahlt, Inventur-abgeschlossen, Bestellvorschlag-versendet und Lieferung-eingegangen. Jeder Event trägt einen Payload mit den relevanten Daten, etwa Bon-Nummer, Zeitstempel, Standort-ID, Artikel und Betrag. Das Format ist meist JSON.

Idempotenz ist das wichtigste technische Prinzip. Jeder Webhook enthält eine eindeutige Event-ID, oft im Header X-Event-Id oder im Payload-Feld id. Dein System speichert verarbeitete IDs und ignoriert Duplikate. Das ist kritisch, weil Retries unvermeidlich sind. Ohne Idempotenz buchst du bei jedem Retry den Bon erneut und das Reporting zeigt überhöhte Umsätze.

Retry-Strategien folgen einem klaren Muster. Der Sender versucht die Zustellung, wartet bei Fehler eine Sekunde, dann zwei, dann vier, dann acht. Diese Exponential-Backoff-Logik gibt deinem System Zeit, sich zu erholen, ohne dass Daten verloren gehen. Übliche Retry-Fenster reichen über 24 Stunden mit zehn bis fünfzehn Versuchen. Wer keine Retries fährt, verliert bei einem zehnminütigen Endpunkt-Ausfall die zugehörigen Bons komplett.

Authentifizierung läuft über HMAC-Signaturen. Der Sender berechnet aus dem Payload und einem geteilten Secret eine Signatur und schickt sie im Header X-Signature. Dein Empfänger berechnet dieselbe Signatur und vergleicht. Stimmen die Werte überein, ist der Webhook echt. Ohne diese Prüfung kann jeder fremde Daten schicken. In der DSGVO-Welt ist das ein Compliance-Risiko, weil personenbezogene Daten ohne Authentifizierung verarbeitet würden.

Eine bewährte Architektur trennt Empfang und Verarbeitung. Dein Endpunkt nimmt den Webhook entgegen, prüft die Signatur, speichert den Event in einer Queue und antwortet sofort mit HTTP 200. Die eigentliche Verarbeitung läuft asynchron im Hintergrund. Das ist wichtig, weil viele Sender bei Antwort-Latenz über fünf Sekunden den Webhook als gescheitert werten und einen Retry auslösen.

Eine Reconciliation gegen die klassische REST-Sicht ist Pflicht. Du summierst täglich alle empfangenen Events und gleichst die Summe mit dem REST-Endpunkt ab. Differenzen über 0,3 Prozent lösen einen Alert aus und werden geprüft. So findest du stille Lücken, etwa wenn ein Webhook während eines Netzwerk-Ausfalls nach allen Retries endgültig verloren ging.

Konkrete Events in der Gastro-Praxis. "Order created" und "order completed" treiben das Umsatz-Reporting. "Invoice paid" stößt die Warenwirtschaft an, weil mit der bezahlten Rechnung die Lieferantenverbindlichkeit aufgelöst wird. "Inventory count completed" triggert die Wareneinsatz-Berechnung. "Shift clocked out" liefert Daten für die Personalkosten-Auswertung. Jeder Event ist klein, in Summe entsteht ein Echtzeit-Bild der operativen Lage.

Webhooks ergänzen klassische Integrationen, ersetzen sie aber selten ganz. Stammdaten wie Artikel, Standorte und Mitarbeitende laufen weiterhin über REST. Stamm-Updates kommen seltener und brauchen keine Echtzeit. Operative Events laufen über Webhooks. Diese Aufteilung reduziert Komplexität und Last auf beiden Seiten der Verbindung. In einem Multi-Standort-Betrieb skaliert das Modell besser als ein reines Polling, weil das System nicht für jede Standorterhöhung mehr Polling-Last aufbauen muss.

Praktisch entscheidet die Latenz-Anforderung über das Muster. Live-Dashboards für Operations-Manager brauchen Sekunden-Reaktion und sind ohne Webhooks nicht baubar. Nächtliche Reporting-Jobs für die Buchhaltung können auch mit Pull arbeiten. Wer beide Anforderungen sauber trennt, betreibt einfacheren Code und stabilere Pipelines.

#Häufige Fehler

• Webhook-Endpunkte ohne HMAC-Signatur. Jeder kann beliebige Daten schicken und die Reporting-Datenbank vergiften.
• Synchrone Verarbeitung im Webhook-Handler. Bei Last-Spitzen läuft die Antwortzeit hoch, der Sender markiert den Webhook als gescheitert und triggert Retries.
• Idempotenz wird nicht abgesichert. Retries werden als neue Events verarbeitet und Bons doppelt gebucht.
• Endpunkte antworten mit HTTP 500 bei kleinen Datenfehlern. Der Sender retryt 15-mal und blockiert die Queue.
• Reconciliation gegen die REST-Sicht wird nicht eingerichtet. Stille Lücken im Reporting werden erst beim Monatsabschluss sichtbar.
• Secrets für die HMAC-Signatur werden im Source-Code statt in einem Secret-Manager abgelegt. Wer den Code sieht, kann eigene Webhooks fälschen.
• Die Antwortzeit wird nicht überwacht. Langsam wachsende Latenz wird übersehen, bis der Sender massiv Retries ausspielt und die Queue blockiert.

Ein konkretes Praxisbeispiel macht den Unterschied deutlich. Eine Café-Kette mit elf Standorten lief drei Monate ausschließlich auf Pull-basiertem Reporting. Daten wurden alle zehn Minuten abgefragt. Die Operations-Manager bemerkten erst am späten Nachmittag, wenn ein Standort vormittags Umsatzeinbrüche hatte, weil die Abweichungen erst im Tagesreport sichtbar wurden. Nach Umstellung auf Webhooks für die wichtigsten Order-Events lag die Latenz unter zwei Minuten. Probleme wie ausgefallene Kasse oder fehlerhafte Karte wurden schon vormittags adressiert, statt nachmittags rekonstruiert. Der Effekt auf den Wareneinsatz war indirekt, aber spürbar. Die Verlinkung mit dem Blog-Beitrag zu Kennzahlen Gastronomie zeigt, wie Echtzeit-Werte Steuerungsentscheidungen verändern.

#So unterstützt Heptic

Heptic Integrationen liefert dokumentierte Webhooks für alle relevanten Events in Inventory, Workforce und Intelligence. HMAC-Signaturen, Idempotenz-Keys und Exponential-Backoff sind eingebaut. Auf Empfangsseite kapseln die Heptic-Adapter für Lightspeed, Orderbird, Gastronovi und weitere POS die Webhook-Logik der jeweiligen Anbieter und normalisieren die Events auf ein einheitliches Datenmodell. So bekommst du Echtzeit-Sicht auf Bestellungen und Inventur ohne eigene Retry-Logik aufbauen zu müssen.

Häufige Fragen

Wann nutze ich Webhooks und wann eine klassische API?

Webhooks sind richtig, wenn du auf Ereignisse sofort reagieren willst, etwa Live-Dashboards oder Sofort-Alerts. Klassische REST-APIs nutzt du für initiale Stammdaten, Backfill historischer Daten und gezielte Pulls. In der Praxis kombinierst du beides. Webhook für Echtzeit, REST als Sicherungsnetz alle 15 bis 30 Minuten. Wer nur Webhooks nutzt, verliert bei Netzwerk-Ausfällen Daten.

Was ist Idempotenz und warum ist sie wichtig?

Idempotenz bedeutet, dass derselbe Webhook beliebig oft verarbeitet werden kann, ohne dass die Daten kaputt gehen. Jeder Webhook enthält einen eindeutigen Event-Identifier. Dein System prüft, ob diese ID schon verarbeitet wurde, und ignoriert Duplikate. Ohne Idempotenz buchst du Bons doppelt, wenn ein Retry ankommt. Saubere Sender liefern den Identifier im Header oder im Payload.

Wie sicher sind Webhooks?

Sicher, wenn du sie richtig betreibst. Standard ist HMAC-Signatur im Header. Der Sender signiert den Payload mit einem geteilten Secret, der Empfänger prüft die Signatur. Zusätzlich solltest du den Endpunkt nur über HTTPS betreiben, IP-Allowlists nutzen, wenn möglich, und Tokens regelmäßig rotieren. Ohne Signatur kann jeder fremde Daten in dein System schieben, das ist DSGVO- und sicherheitskritisch.

Zuletzt aktualisiert: Mai 2026