Quellen

Eine Quelle ist eine URL, die Sie einem Anbieter geben — Stripe, GitHub oder jedem anderen, der seine Webhooks signiert —, damit er an uns senden kann. Wir prüfen die Signatur jedes Requests, machen daraus ein Event und stellen es an Ihre Endpoints zu, genau wie ein Event, das Sie selbst veröffentlicht haben: dieselben Abos, dieselben Retries, dieselbe Dead-Letter-Queue.

Nutzen Sie eine Quelle, wenn Sie einen zentralen Ort für Webhook-Traffic in beide Richtungen wollen oder wenn mehrere Ihrer Dienste die Events eines Anbieters empfangen sollen, ohne dass jeder einzeln die Signatur von Stripe prüft.

Wie aus einem Request Zustellungen werden

1. Der Anbieter sendet per POST an die Ingest-URL der Quelle, https://webhooks.nimbusnexus.net/v1/ingest/{source_id}.
2. Wir prüfen die Signatur über genau die empfangenen Bytes, gegen das Signatur-Secret der Quelle.
3. Der Body muss ein JSON-Objekt sein. Wir lesen daraus den Event-Typ (siehe Event-Typen aus einer Quelle).
4. Das Event wird im Projekt der Quelle veröffentlicht und mit den Abos Ihrer Endpoints abgeglichen, wodurch pro passendem Endpoint eine Zustellung entsteht.
5. Der Anbieter erhält 202. Ihre Endpoints erhalten das Event, signiert mit ihrem Secret, nicht mit dem des Anbieters.

Die Ingest-URL ist der einzige Teil von Webhooks, der Requests ohne API-Key annimmt: Die Signatur des Anbieters ist das Credential.

Anbieter und ihre Signaturen

Alle drei verwenden HMAC-SHA256. generic ist dasselbe Verfahren, mit dem wir unsere eigenen Zustellungen signieren, sodass der Endpoint eines Webhooks-Workspaces die Quelle eines anderen speisen kann und jeder Absender, den Sie kontrollieren, mit wenigen Zeilen auf diese Weise signieren kann.

Quelle anlegen

In der Konsole: Sources → New source (auch auf der Seite Overview). Oder über die API:

curl -sX POST https://webhooks.nimbusnexus.net/v1/sources \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "stripe",
        "name": "Stripe live",
        "secret": "whsec_…",
        "event_type_prefix": "stripe."
      }'

• Stripe und GitHub: Fügen Sie das Signatur-Secret ein, das Ihnen der Anbieter anzeigt. Eine Quelle, die ohne Secret angelegt wird, ist zunächst deaktiviert; fügen Sie das Secret später mit rotate-secret hinzu und aktivieren Sie die Quelle.
• Generic: Lassen Sie secret weg, dann erzeugen wir eines und geben es einmal in dieser Antwort zurück.

Die Antwort enthält ingest_url. Tragen Sie die URL in die Webhook-Einstellungen des Anbieters ein und fügen Sie einen Endpoint hinzu, der die erwarteten Typen abonniert (oben prefix stripe.).

Event-Typen aus einer Quelle

Jeder Request braucht einen Event-Typ, den Endpoints abonnieren können. Eine Quelle ermittelt ihn in dieser Reihenfolge:

1. Dort, wo sie laut Ihrer Vorgabe suchen soll: in einem Header des Requests oder in einem JSON-Pfad mit Punkten im Body (data.object.type).
2. Andernfalls an der eigenen Stelle des Anbieters: type im Body bei Stripe und generic, der Header X-GitHub-Event bei GitHub.
3. Liefert keines von beiden einen Wert: der Standardtyp der Quelle und, falls es keinen gibt, webhook.received.

Das Präfix der Quelle wird vorangestellt (stripe. + invoice.paid → stripe.invoice.paid), was die Typen zweier Anbieter in einem Projekt auseinanderhält. Wenn Ihre Liste der Event-Typen webhook.received zeigt, hat eine Quelle Requests ohne lesbaren Typ empfangen: Legen Sie für diese Quelle einen Standardtyp oder einen JSON-Pfad fest.

Die eigene Event-ID des Anbieters (evt_… bei Stripe, die Delivery-ID bei GitHub) ist der Idempotency-Key. Wenn ein Anbieter ein Event wiederholt, das wir bereits angenommen haben, erhält er also erneut 202, und nichts wird doppelt zugestellt.

Was der Anbieter sieht

Anbieter wiederholen bei allem außer 2xx, eine Abweisung geht auf ihrer Seite also nicht verloren — um aber zu sehen, warum wir abgewiesen haben, schalten Sie die Aufzeichnung für die Quelle ein und lesen Sie Erfasste Requests.

Secret rotieren

Wenn der Anbieter sein Secret wechselt, senden Sie das neue:

curl -sX POST https://webhooks.nimbusnexus.net/v1/sources/src_…/rotate-secret \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret": "whsec_new…"}'

Das vorherige Secret verifiziert noch 24 Stunden lang weiter, sodass Requests, die mit dem einen oder dem anderen signiert sind, angenommen werden, während der Anbieter umstellt. Bei einer Quelle vom Typ generic senden Sie einen leeren Body, und wir erzeugen das neue Secret.

Nächste Schritte

• Erfasste Requests — die Requests sehen, wie eine Quelle sie empfangen hat, Abweisungen eingeschlossen.
• Quellen in der API-Referenz — jede Operation für Quellen, mit den Aufrufen für SDK und CLI.
• Event-Typen — der Katalog der Typen und was mit einem unbekannten geschieht.
• Zustellungen und Retries — was geschieht, nachdem ein Event veröffentlicht wurde.
• Überblick über Webhooks — die Objekte und wie sie zusammenpassen.