Webhook-Payloads erklärt

Anatomie eines Payloads

Fast immer JSON, fast immer mit drei Zutaten: was passiert ist (Ereignistyp), womit (das Objekt) und wann (Zeitstempel oder ID).

{
  "type": "payment_intent.succeeded",   ← Ereignistyp
  "created": 1690000000,                ← wann
  "data": {                             ← das Objekt
    "object": { "id": "pi_3N…", "amount": 4999, "currency": "eur" }
  }
}

Die drei üblichen Muster

1. Typisierter Umschlag (Stripe, Vercel)

Eine Hülle mit type und einem verschachtelten data-Objekt. Ein Endpoint empfängt alle Ereignistypen; du verzweigst über type. Ausführlich, aber selbsterklärend.

2. Ereignis im Header (GitHub, GitLab)

Der Body ist das Objekt selbst; der Ereignistyp steht in einem Header wie X-GitHub-Event: push. Kompakt, aber du musst Header lesen, um zu wissen, was ankam.

3. Flaches Objekt (Shopify, viele kleine Tools)

Der Body ist schlicht die Ressource – eine Bestellung, ein Kunde. Der Ereignistyp kommt aus dem Header (X-Shopify-Topic) oder aus der URL, die du pro Ereignis registriert hast.

Die relevanten Felder finden

Lies nicht zuerst die Doku – logge einen echten Payload und schau ihn an. Jeder Anbieter hat einen „Testereignis senden“-Knopf, und Webhook-Testdienste zeigen den rohen Body. Dann pick dir die zwei, drei Felder heraus, die du wirklich brauchst: eine ID zur Deduplizierung, einen Betrag, einen Namen.

Was in der Praxis beißt

• Beträge stehen meist in Cent. 4999 heißt 49,99 € – fast jede Payment-API macht das so.
• Felder können fehlen. Optionale Felder verschwinden ganz, statt null zu sein – defensiv zugreifen.
• Payloads wachsen. Anbieter ergänzen Felder ohne Vorwarnung; nie von einer festen Form ausgehen.
• Test-Payloads unterscheiden sich. Der „Test senden“-Knopf erzeugt oft ein Gerüst mit Dummy-IDs – bau nicht allein darauf.

Payload → Push-Benachrichtigung

Wenn ein Webhook einfach nur dein Handy erreichen soll, wird die Payload-Frage klein: Webhooky liest title, message, sound und vibrate, falls vorhanden, und zeigt sonst die Texte, die du für den Endpoint konfiguriert hast – so entsteht auch aus einem Payload, den du nicht kontrollierst, eine lesbare Benachrichtigung. Details in der API-Doku, Hintergrund unter Was ist ein Webhook.

Hol dir Webhooky

Kostenlos für deine ersten 100 Benachrichtigungen – Endpoint in zwei Minuten eingerichtet.