{"canonical_url":"https://engineer.company/de/glossary/webhook/","content_markdown":"# Webhook\n\n## Was es ist\n\nEin Webhook ist eine HTTP-Anfrage, die ein Dienst an einen anderen sendet, sobald\nbei ihm etwas passiert: Eine Zahlung wird abgewickelt, eine Rechnung bezahlt oder\neine längere Aufgabe abgeschlossen. Der Empfänger hinterlegt vorher eine URL, an\ndie der Absender eine Beschreibung jedes Ereignisses schickt. Die Spezifikation\nStandard Webhooks bezeichnet Webhooks als gängige Bezeichnung für HTTP-Callbacks\nund beschreibt sie als Kanal, über den ein Dienst einem anderen ein Ereignis\nmeldet. Gelegentlich wird der Begriff getrennt als web hook geschrieben. Stripe,\nGitHub und die Spezifikation schreiben ihn jedoch als ein Wort.\n\nDie Spezifikation beschreibt einen Webhook auch als Teil der API eines Dienstes,\ngewissermaßen als umgekehrt arbeitende API. Normalerweise ruft der Client den\nDienst auf, wenn er etwas braucht. Bei einem Webhook ruft der Dienst den Client\nauf, wenn es Neuigkeiten gibt. Bei einer typischen API-Integration betreiben beide\nSeiten HTTP-Server: einer nimmt API-Aufrufe entgegen, der andere Webhooks. Ein\nDienst kann aber auch Webhooks senden, ohne selbst eine Anfrage-API anzubieten.\nDer Absender heißt Producer, der Empfänger Consumer. Die vom Empfänger hinterlegte\nURL ist sein Webhook-Endpunkt.\n\nDie Spezifikation empfiehlt HTTP POST mit einem JSON-Rumpf, schreibt aber weder\nFormat noch Aufbau der Nutzdaten vor. Der vorgeschlagene Rumpf enthält einen `type`\nmit Punkten und hierarchischer Gliederung, etwa `invoice.paid`, einen `timestamp`\nfür den Ereigniszeitpunkt in ISO 8601 und die Ereignisdaten entweder unter `data`\noder auf oberster Ebene. Zusätzliche Metadaten können an beiden Stellen stehen.\nZustellungsmetadaten gehören in die Header: `webhook-id` bezeichnet das Ereignis,\n`webhook-timestamp` hält den Zeitpunkt dieses Versuchs in Unix-Sekunden fest, und\n`webhook-signature` bestätigt seine Echtheit. Stripe und GitHub verwenden eigene\nHeadernamen, darunter `Stripe-Signature` und `X-Hub-Signature-256`. Auch ihre\nPrüfregeln unterscheiden sich: Stripe signiert einen Zeitstempel des Versuchs\nzusammen mit dem Rumpf, während GitHubs HMAC nur den Rumpf abdeckt.\n\nDie Nutzdaten können vollständig sein und das gesamte geänderte Objekt enthalten\noder schlank ausfallen, mit kaum mehr als einer Kennung. Im zweiten Fall ruft der\nEmpfänger den Rest über die API ab. Die Spezifikation wägt beides ab. Vollständige\nNutzdaten ersparen zusätzliche API-Aufrufe. Schlanke Nutzdaten bedeuten weniger zu\nerzeugende und zu sendende Daten, mehr Flexibilität und mehr Spielraum für spätere\nÄnderungen: Sie lassen sich jederzeit zu vollständigen Nutzdaten erweitern, nicht\naber umgekehrt. Zudem wird der Datenzugriff nachvollziehbar, weil der Empfänger\nexplizit anfordern muss, was er liest. In beiden Fällen rät die Spezifikation zu\nkleinen Nutzdaten, gewöhnlich unter 20 kB. Stripe bietet ein schlankes Format an\nund kennzeichnet es als Empfehlung.\n\n## Warum es wichtig ist\n\nOhne Webhooks muss ein System immer wieder bei einem anderen System nachfragen,\nob sich etwas geändert hat. Meist lautet die Antwort, dass nichts passiert ist.\nVon einer tatsächlichen Änderung erfährt es trotzdem erst beim nächsten Abruf. Ein Webhook kehrt das um: Der Dienst,\nder von dem Ereignis weiß, ruft den Empfänger einmal auf, sobald es eintritt.\nSo melden Zahlungsanbieter, Codehosting-Dienste und E-Mail-Anbieter Ergebnisse an\ndie Systeme zurück, die auf ihnen aufbauen.\n\nDiese Umkehr hat ihren Preis, überwiegend auf der Empfangsseite. Ihr Endpunkt ist\neine öffentliche URL, an die jeder im Internet POST-Anfragen senden kann. Einer\neingehenden Anfrage ist nicht anzusehen, wer sie geschickt hat. Deshalb verlangt\ndie Spezifikation für jede sichere Implementierung eine Echtheitsprüfung.\nDie Zustellung wird wiederholt, bis der Empfänger mit einem 2xx-Status antwortet\noder die Zustellungsrichtlinie aufgibt. Dasselbe Ereignis kann daher mehrfach\nankommen; Stripe warnt ausdrücklich vor gelegentlichen Duplikaten. Auch die\nReihenfolge ist nicht zugesichert: Stripe garantiert nicht, dass Ereignisse in\nder Reihenfolge ihres Entstehens eintreffen.\n\nDer Producer muss seinerseits weitere Zustellversuche unternehmen. Die Spezifikation\nempfiehlt einen über mehrere Tage verteilten Wiederholungsplan mit exponentiell\nwachsenden Wartezeiten und zufälligen Abweichungen. Ihr Beispiel umfasst zehn\nVersuche; der letzte erfolgt 75 Stunden, 35 Minuten und 5 Sekunden nach dem ersten.\nStripe wiederholt im Livebetrieb bis zu drei Tage lang. Ein Empfänger, der in\ndiesem Zeitraum wieder erreichbar ist, erhält die ausstehenden Zustellungen\nautomatisch. Danach\nlässt Stripe Ereignisse bis zu 15 Tage nach ihrer Erstellung manuell erneut senden,\nmit seiner CLI bis zu 30 Tage. Scheitert die Zustellung über längere Zeit weiter,\nempfiehlt die Spezifikation, den Consumer über einen anderen Kanal, etwa per\nE-Mail, zu informieren und den Endpunkt zu deaktivieren.\n\n## Wie es in der Praxis aussieht\n\nDies sind die Header einer Zustellung im Format der Spezifikation. Kennung,\nZeitstempel und Signatur sind deren eigene Beispielwerte; der `Host`-Wert und\nder Pfad sind erfunden:\n\n```http\nPOST /webhooks/billing HTTP/1.1\nHost: example.com\nContent-Type: application/json\nwebhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\nwebhook-timestamp: 1674087231\nwebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n```\n\nDazu gehört dieser Rumpf: schlanke Nutzdaten aus derselben Spezifikation, hier\nlesbar eingerückt. Für die Übertragung empfiehlt sie eine minimierte Darstellung:\n\n```json\n{\n  \"type\": \"contact.created\",\n  \"timestamp\": \"2022-11-03T20:26:10.344522Z\",\n  \"data\": {\n    \"id\": \"1f81eb52-5198-4599-803e-771906343485\"\n  }\n}\n```\n\nDas Präfix `v1` kennzeichnet eine symmetrische Signatur: HMAC-SHA256 über die\nmit Punkten verbundenen Werte für Ereigniskennung, Zeitstempel und Rumpf, mit einem\nnur diesem Endpunkt zugeordneten Geheimnis als Schlüssel. Da Kennung und\nZeitstempel zusammen mit dem Rumpf signiert sind, lässt sich keiner dieser Werte\nändern, ohne die Signatur ungültig zu machen. Die Spezifikation erlaubt außerdem\nasymmetrische ed25519-Signaturen mit der Kennzeichnung `v1a`. Sie empfiehlt sie,\nwenn unterschiedliche Parteien für die Sicherheit von Producer und Consumer\nverantwortlich sind.\n\nAuch GitHub signiert Zustellungen mit HMAC-SHA256. Es schreibt den hexadezimalen\nPrüfwert in `X-Hub-Signature-256` mit dem Präfix `sha256=` und veröffentlicht ein\nGeheimnis, Nutzdaten und eine Signatur zum Testen einer Prüffunktion. Diese\nPython-Prüffunktion wurde gegen das Beispiel geprüft:\n\n```python\nimport hashlib\nimport hmac\n\n\ndef verify(body: bytes, secret: str, header: str) -\u003e bool:\n    mac = hmac.new(secret.encode(\"utf-8\"), body, hashlib.sha256)\n    expected = \"sha256=\" + mac.hexdigest()\n    return hmac.compare_digest(expected, header)\n\n\nsecret = \"It's a Secret to Everybody\"\nheader = (\n    \"sha256=757107ea0eb2509fc211221cce984b8a\"\n    \"37570b6d7586c22c46f4379c8b043e17\"\n)\nprint(verify(b\"Hello, World!\", secret, header))  # True\nprint(verify(b\"Hello, World! \", secret, header))  # False\n```\n\nEin einziges zusätzliches Leerzeichen am Ende des Rumpfs lässt die Prüfung\nscheitern. `hmac.compare_digest` benötigt dieselbe Zeit, ob sich die Zeichenketten\nfrüh oder spät unterscheiden. GitHubs Dokumentation warnt davor, Signaturen mit\neinem einfachen `==` zu vergleichen. Ein solider Handler arbeitet dann in fester\nReihenfolge: die unveränderten Bytes lesen, die Signatur über genau diese Bytes\nprüfen, gegebenenfalls die Aktualität eines vom Producer signierten\nVersuchszeitstempels prüfen, nachsehen, ob die Ereigniskennung schon bekannt ist,\ndas Ereignis in eine Warteschlange stellen und mit 2xx antworten. Erst danach\nbeginnt die eigentliche Arbeit. Stripe nennt als Beispiel, mit 200 zu antworten,\nbevor die Rechnung eines Kunden im Buchhaltungssystem als bezahlt markiert wird.\n\nZwei Projekte im Portfolio dieser Website behandeln Webhooks aus Sicht des\nEmpfängers. Bei den\n[Berechtigungen aus Stripe und In-App-Käufen](/de/portfolio/built-stripe-and-in-app-purchase-entitlements/)\nmuss ein Abonnement unter anderem einen doppelt eintreffenden Webhook und eine\nvertauschte Reihenfolge verkraften. Beim\n[E-Mail-System mit Ausfallsicherung und Zustellungsprotokollierung](/de/portfolio/built-email-with-failover-and-delivery-logging/)\nmelden eingehende Webhooks, was die einzelnen Anbieter mit einer Nachricht getan\nhaben. Das Projekt erfasst sowohl das Gesendete als auch die Rückmeldungen in\neinem Sendeprotokoll und einer Tabelle der Zustellungsereignisse.\n\n## Wo es schiefgeht\n\n**Die Signatur stimmt nie.** Häufig zerlegt das Framework des Empfängers den\nJSON-Rumpf, und der Code serialisiert ihn erneut, bevor er den HMAC berechnet.\nDie Spezifikation nennt das einen sehr häufigen Fehler: JSON-Serialisierung\nunterscheidet sich zwischen Implementierungen, und schon ein zusätzliches\nLeerzeichen macht die Signatur ungültig. Stripe verlangt aus demselben Grund den\nunveränderten Rumpf und warnt, dass jede Bearbeitung die Prüfung scheitern lässt.\nGitHub ergänzt, dass ein vorgeschalteter Proxy oder Lastverteiler weder Nutzdaten\nnoch Header verändern darf und die Nutzdaten als UTF-8 behandelt werden sollen.\nBerechnen Sie die Signatur über die Bytes genau in der empfangenen Form, bevor\ndiese geparst werden.\n\n**Dasselbe Ereignis kommt zweimal an.** Sowohl Wiederholungen als auch\nNetzprobleme erzeugen Duplikate. Nach der Spezifikation bleibt `webhook-id` bei\njedem erneuten Versuch desselben Ereignisses gleich und dient als\nIdempotenzschlüssel. Ihr Beispiel speichert die Kennungen fünf Minuten in Redis.\nStripe empfiehlt, bereits verarbeitete Ereignis-IDs zu protokollieren und bekannte\nzu überspringen. Es weist auch darauf hin, dass ein einzelner zugrunde liegender\nVorgang zwei unterschiedliche Event-Objekte erzeugen kann. Erkennbar sind sie an\nder Objekt-ID in `data.object` zusammen mit dem Ereignistyp. GitHubs Header\n`X-GitHub-Delivery` bleibt bei einer erneuten Zustellung gleich. Die Verarbeitung\nsoll idempotent sein, sodass eine zweite Zustellung nichts ändert.\n\n**Eine abgefangene Zustellung wird erneut abgespielt.** Eine gültige Signatur\nbleibt gültig. Wer eine Zustellung abfängt, kann sie daher noch einmal senden.\nDeshalb wird der Zeitstempel mit signiert: Die Spezifikation verlangt, einen\n`webhook-timestamp` außerhalb der zulässigen Toleranz zurückzuweisen. Stripes\nBibliotheken verwenden standardmäßig fünf Minuten. Stripe warnt, dass die\nToleranz 0 die Prüfung vollständig ausschaltet, und empfiehlt NTP für eine genaue\nServeruhr. Sowohl Stripe als auch die Spezifikation versehen jeden erneuten Versuch\nmit einem neuen Zeitstempel. Das Alter wird damit ab diesem Versuch und nicht ab\ndem ursprünglichen Ereignis gemessen; ein verzögerter Versuch kann trotzdem\naußerhalb der Toleranz liegen. Bewahren Sie bekannte Kennungen mindestens so lange\nwie die Toleranz auf. Dann wird jede Wiederholung innerhalb dieses Zeitfensters\nals Duplikat erkannt.\n\n**Ereignisse kommen in vertauschter Reihenfolge an.** Stripes Beispiel: Beim\nAnlegen eines Abonnements können `customer.subscription.created`, `invoice.created`,\n`invoice.paid` und, falls eine Belastung erfolgt, `charge.created` entstehen.\nNichts garantiert diese Reihenfolge bei der Zustellung. Das Feld `created` von\nStripes Snapshot-Ereignissen hat eine Auflösung von einer Sekunde. Mehrere\nEreignisse können daher denselben Zeitstempel tragen. Stripe rät davon ab, ihn zum\nSortieren oder Erkennen von Duplikaten zu verwenden. Ein robuster Ansatz nimmt\nein Ereignis als Hinweis auf eine Änderung und ruft vor jeder weiteren Handlung\nden aktuellen Zustand des Objekts über die API ab.\n\n**Der Handler ist zu langsam.** GitHub erwartet innerhalb von 10 Sekunden eine\n2xx-Antwort. Danach beendet es die Verbindung und wertet die Zustellung als\ngescheitert. Die Spezifikation empfiehlt ein Anfragezeitlimit zwischen 15 und 30\nSekunden. Erledigt der Handler die eigentliche Arbeit sofort im Anfrageablauf,\nüberschreitet er das Zeitlimit; der Producer versucht es erneut, und die Arbeit\nläuft zweimal. Stripe und GitHub empfehlen beide eine Warteschlange. Stripe nennt\ndie Lastspitze am Monatsanfang, wenn alle Abonnements verlängert werden.\n\n**Nur 2xx zählt.** Alles andere gilt sowohl nach der Spezifikation als auch bei\nStripe als Fehler, einschließlich 3xx. Bei einem Endpunkt hinter einer Weiterleitung\nscheitert deshalb jeder Zustellversuch, bis seine hinterlegte URL aktualisiert wird.\nEinigen Statuscodes gibt die Spezifikation eine Bedeutung für den Producer:\n`410 Gone` heißt, den Endpunkt zu deaktivieren; 429, 502 und 504 bedeuten, langsamer\nzu werden. Ein `retry-after`-Header soll den nächsten Versuch beeinflussen.\n\n**Für den Producer ist die URL eine potenziell feindliche Eingabe.** Kunden\nkönnen jede beliebige URL angeben, die die Server des Producers dann aufrufen.\nDie Spezifikation bezeichnet Webhook-Systeme als besonders anfällig für Server-Side\nRequest Forgery (SSRF): Eine URL mit interner Adresse bringt den Producer dazu,\nsein eigenes Netz aufzurufen. Sie empfiehlt, jede Webhook-Anfrage über einen Proxy\nzu senden, der interne IP-Adressen filtert, etwa Stripes smokescreen. Die\nWebhook-Worker sollen in einem privaten Subnetz laufen, das keine internen\nDienste erreichen kann.\n\n## Weiterführende Lektüre\n\n- [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)\n  — Version 1.0.0: Aufbau der Nutzdaten, Signaturverfahren, Header,\n  Wiederholungsplan, Statuscodes und SSRF.\n- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)\n  — schlanke und Snapshot-Nutzdaten, Wiederholungen, doppelte und vertauschte\n  Ereignisse sowie Schutz vor dem erneuten Abspielen.\n- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)\n  — GitHubs Empfehlungen: wenige Ereignisse, ein Webhook-Geheimnis, HTTPS,\n  Antwort innerhalb von 10 Sekunden, erneute Zustellung und `X-GitHub-Delivery`.\n- [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)\n  — `X-Hub-Signature-256`, Vergleich mit konstanter Laufzeit und ein Testbeispiel\n  für eine Prüffunktion.\n\n\u003chttps://engineer.company/de/glossary/webhook/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Wie ein Dienst Ereignisse an einen Server meldet, wie signierte Zustellungen aussehen und warum Empfänger Duplikate und Wiederholungen erwarten müssen.","formats":{"gemtext":"https://engineer.company/de/glossary/webhook/index.gmi","gopher":"https://engineer.company/de/glossary/webhook/gophermap","html":"https://engineer.company/de/glossary/webhook/","json":"https://engineer.company/de/glossary/webhook/index.json","markdown":"https://engineer.company/de/glossary/webhook/index.md","pdf":"https://engineer.company/de/glossary/webhook/index.pdf"},"kind":"page","language":"de","title":"Was ist ein Webhook?","url":"https://engineer.company/de/glossary/webhook/","version":1}