(Webhook-Zustellung · Nautilus)
Ihr Produkt veröffentlicht ein Ereignis mit einem API-Aufruf. Nautilus stellt es in die Warteschlange, signiert es und liefert es an jeden Endpoint, der diesen Ereignistyp abonniert hat. Eine fehlgeschlagene Zustellung wird nach festem Zeitplan wiederholt, und jeder Versuch erscheint mit der erhaltenen Antwort in Ihrem Dashboard.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer vrn_relay_•••" \
-d '{"event_type":"user.created","payload":{"id":"usr_123"}}'(Bauen oder kaufen)
Die erste Version ist ein POST-Request in einer Retry-Schleife. Einfach ist das nicht mehr, wenn der Server eines Kunden ein Wochenende lang ausfällt, wenn ein Handler-Deployment kaputt ausgeliefert wird und eine Stunde Ereignisse erneut gesendet werden muss, und wenn ein langsamer Endpoint beginnt, alle anderen aufzuhalten.
Selbst bauen
Webhook-Zustellung in Nautilus
(Kernfunktionen)
(01)
Eine Antwort außer 2xx oder eine Zeitüberschreitung zählt als fehlgeschlagener Versuch. Die Nachricht wird in wachsenden Abständen wiederholt: 8 Versuche über etwa 28 Stunden, derselbe Zeitplan für jeden Endpoint. Die Zustellung ist at-least-once, ein erneuter Versuch kann den Server Ihres Kunden also mehr als einmal erreichen.
(02)
Jede Nachricht wird mit HMAC SHA-256 signiert, mit einem Secret, das zu einem Endpoint gehört. Jede Zustellung trägt drei Header (svix-id, svix-timestamp und svix-signature), und die Signatur deckt ID, Zeitstempel und Body ab, sodass Ihre Kunden prüfen können, wer sie gesendet hat, und eine wiederholt eingespielte Anfrage ablehnen können.
(03)
Das Veröffentlichen eines Ereignisses gibt 202 zurück, sobald die Nachricht in der Warteschlange ist. Die Zustellung an die Server Ihrer Kunden erfolgt danach, sodass ein langsamer oder toter Endpoint die Anfrage nicht verlangsamt, auf die Ihr eigener Code wartet.
(04)
Veröffentlichen Sie ein Ereignis, zum Beispiel user.created, und es wird an jeden Endpoint geliefert, der diesen Ereignistyp abonniert hat. Fügen Sie einer Nachricht einen Channel hinzu, um nur die Endpoints zu erreichen, die darauf hören.
(05)
Jeder Versuch wird mit Zeitpunkt, Antwortcode und dem Antwort-Body Ihres Servers gespeichert, damit Sie sehen, warum eine Zustellung fehlgeschlagen ist. Im Tab Events Ihres Dashboards können Sie eine Zustellung erneut senden oder alles, was seit einem von Ihnen gewählten Zeitpunkt fehlgeschlagen ist, per Replay nachholen, bis zu 14 Tage zurück.
(06)
Senden Sie einen idempotency_key, und ein wiederholter Aufruf liefert die ursprüngliche Nachricht zurück, statt eine zweite zu erzeugen. Die Zustellung selbst erfolgt mindestens einmal: Ein Retry kann Ihre Kunden erneut erreichen, deshalb sollten diese über den Header svix-id deduplizieren, der bei jedem Versuch für dieselbe Nachricht gleich bleibt.
(Teil von Nautilus)
Die Webhook-Zustellung ist ein Teil von Nautilus, kein eigener Dienst. Sie teilt sich Konto und Dashboard mit Anmeldung und Cron-Jobs. Anmeldeereignisse wie eine neue Registrierung erreichen Ihr Backend auf dieselbe Weise, als signierte und wiederholte Webhooks.
(Entwicklererfahrung)
Veröffentlichen Sie ein Event mit einem einzigen Aufruf — über ein offizielles SDK für Node, Python, PHP oder Rust, oder per einfachem HTTP-Request, wenn Sie keine Abhängigkeit hinzufügen möchten.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer $VERNE_RELAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "subscription.renewed",
"payload": { "user_id": "usr_987", "plan": "pro_tier" },
"idempotency_key": "evt_5f3c9a"
}'(FAQ)
Nautilus erzeugt für jeden Endpoint ein eigenes Secret und signiert jede ausgehende Anfrage mit HMAC SHA-256. Jede Zustellung trägt drei Header: svix-id, svix-timestamp und svix-signature. Die Signatur wird über svix-id, svix-timestamp und den rohen Body berechnet, durch Punkte verbunden, sodass der Empfänger die Echtheit prüfen und eine Wiederholung ablehnen kann. Die offiziellen Svix-Bibliotheken prüfen das alles mit einem Aufruf.
Jede Antwort außer 2xx und jede Zeitüberschreitung zählt als fehlgeschlagener Versuch. Die Nachricht wird nach einem festen Zeitplan mit wachsenden Abständen wiederholt: 8 Versuche über etwa 28 Stunden, damit sich noch erholende Server nicht überlastet werden. Der Zeitplan ist für alle Endpoints gleich und nicht änderbar. Ein Endpoint, der fünf Tage lang bei jedem Versuch scheitert, wird deaktiviert, und nichts benachrichtigt Sie, werfen Sie also ab und zu einen Blick auf den Tab Events. Sobald Ihr Server wieder läuft, können Sie fehlgeschlagene Zustellungen aus dem Dashboard erneut senden oder alles, was seit einem von Ihnen gewählten Zeitpunkt fehlgeschlagen ist, per Replay nachholen.
Ja. Machen Sie Ihren lokalen Endpoint mit einem Tunnel wie ngrok oder Cloudflare Tunnel erreichbar und fügen Sie diese URL im Dashboard als Endpoint hinzu. Nutzen Sie einen Live-Key: Ereignisse, die mit einem Test-Key gesendet werden, werden angenommen, aber nicht zugestellt. Im Zustell-Log können Sie beim Testen jeden Versuch einsehen.
Das können Sie, und es ist weit mehr als ein POST: eine Queue und exponentielles Backoff, Secrets pro Endpoint und HMAC-Signierung, eine Möglichkeit, einen wiederholten Versand zu deduplizieren, und ein Zustell-Log, das Ihr Support durchsehen kann, wenn ein Kunde sagt, das Ereignis sei nie angekommen. Nautilus hat diese Liste fertig, und Sie zahlen pro API-Anfrage. Was Sie aufgeben, ist Kontrolle: Der Wiederholungszeitplan ist fest, Endpoints werden im Dashboard statt per API hinzugefügt, und die Engine darunter ist Svix, das Open Source ist, falls Sie es je selbst betreiben wollen.
Heute nicht über die API. Endpoints werden im Dashboard angelegt: Wenn Ihre Kunden ihre eigene URL in die Einstellungen Ihres Produkts einfügen sollen, müssen Sie diese Ansicht selbst bauen, und vorerst trägt jemand mit Dashboard-Zugang die URL ein. Ereignisse zu veröffentlichen und wieder auszulesen ist über die API möglich.
(Loslegen)
Die Webhook-Zustellung ist ein Teil von Nautilus: dasselbe Konto und dasselbe Dashboard wie Anmeldung und Cron-Jobs.
Was der Eigenbau kostet
Der Bau ist nicht der teure Teil. Eine Queue, ein Retry mit Backoff und ein Signatur-Helfer sind eine Wochenarbeit, und die meisten Teams kommen dort problemlos an. Teuer wird die Woche danach, wenn ein Kunde sagt, ein Event sei nie angekommen, und die Antwort darauf heißt: Logs von Hand lesen. Und es hört nicht auf, denn jeder neue Kunden-Endpoint ist ein neuer Weg, auf dem Zustellung scheitern kann.
Es kostet außerdem Aufmerksamkeit an einer Stelle, die nichts einbringt. Niemand hat Ihr Produkt gewählt, weil Ihre Retries Exponential Backoff verwenden. Ein Webhook, der still nicht mehr ankommt, ist aber erst ein Support-Ticket, dann ein Gespräch über eine Rückerstattung und manchmal ein Kunde, der geht. Hohe Folgen, kein Verdienst — genau die Form einer Sache, die man kauft statt sie zu bauen.
Wenn Sie es lieber selbst bauen: bauen Sie es. Der Entwurf ist kein Geheimnis, und wir würden die meisten derselben Entscheidungen treffen. Rechnen Sie es nur als Dienst, den Sie jahrelang betreiben, nicht als Sprint. Wenn Sie es lieber nicht tun: Ein Endpoint, den Sie schon haben, kann signierte, wiederholte Zustellungen empfangen, sobald Sie einen API-Key haben und seine URL im Dashboard steht, und die ersten 3.000 Anfragen jeden Monat sind gratis.