Orbit Webhooks

Webhooks senden ein signiertes HTTP POST an eine URL Ihrer Wahl jedes Mal, wenn sich der Status einer Bereitstellung ändert. So erfährt Ihr Team von einem fehlgeschlagenen Build in dem Kanal, den es ohnehin beobachtet, statt später von einem Kunden davon zu erfahren.

Wo sich Webhooks befinden

Öffnen Sie Orbit, klicken Sie auf das Projekt und wählen Sie Webhooks unter der Gruppe Configure in der Projekt-Registerkartenleiste. Die Seite trägt den Titel Webhooks und beschreibt sich selbst als Empfänger von HTTP POST-Benachrichtigungen, wenn sich Bereitstellungen ändern. Slack, Discord und generisches JSON werden unterstützt.

Einen Webhook hinzufügen

1. Geben Sie in der Karte Add a webhook einen Label ein. Etwa das Ziel, an das es gesendet wird.
2. Fügen Sie die URL ein. Sie muss mit https:// beginnen.
3. Aktivieren Sie unter Trigger on die gewünschten Ereignisse.
4. Klicken Sie auf Add webhook.

Das Signing Secret wird sofort nach der Erstellung einmalig angezeigt, zusammen mit einer Warnung, dass es nicht erneut angezeigt wird. Kopieren Sie es, bevor Sie die Seite verlassen.

Ein Projekt kann bis zu zehn Webhooks enthalten. Das Hinzufügen eines elften wird mit einer Meldung abgelehnt, die das Limit nennt.

Die fünf Ereignisse

Wählen Sie gezielt aus. Das Abonnieren aller fünf Ereignisse bei einem aktiven Projekt verwandelt einen nützlichen Alert-Kanal in Rauschen, das jeder stummschaltet. Für die meisten Teams ist Failed allein der richtige Anfangspunkt, wobei Succeeded nur dort hinzugefügt werden sollte, wo eine Benachrichtigung über die Bereitstellung wirklich nützlich ist, etwa in einem Produktionskanal.

Slack und Discord

Falls die URL ein Slack-Incoming-Webhook oder ein Discord-Webhook ist, erkennt Orbit dies anhand der URL und sendet eine formatierte Nachricht statt rohem JSON. Die Seite zeigt dies unter dem URL-Feld an: Slack- und Discord-URLs werden automatisch erkannt.

Die formatierte Nachricht enthält den Projektnamen, das Ereignis, den Branch, den kurzen Commit, die Build-Zeit, die bereitgestellte URL und den Fehlertext, wenn etwas fehlgeschlagen ist. Die Farbe folgt dem Ereignis, sodass eine rote Karte im Kanal einen Fehler anzeigt, ohne dass jemand sie lesen muss.

Nichts anderes ist erforderlich. Erstellen Sie den Incoming Webhook in Slack oder Discord, fügen Sie die URL hier ein, wählen Sie Ihre Ereignisse aus, und Sie sind fertig.

Generische JSON-Payloads

Jede andere URL erhält einen JSON-Body. Die Felder sind:

Verwenden Sie deliveryId, um Ihren Endpunkt idempotent zu machen. Wenn Sie eine Auslieferung wiederholen oder ein Netzwerkfehler eine Duplikat verursacht, können Sie anhand der ID erkennen, dass Sie diese bereits verarbeitet haben.

Die Signatur verifizieren

Jede Auslieferung trägt drei Header:

• X-Orbit-Signature-256, ein HMAC-SHA256 des genauen Request-Body mit Ihrem Signing Secret, formatiert als sha256= gefolgt vom Hex-Digest.
• X-Orbit-Event, der Ereignisname.
• X-Orbit-Delivery, die Auslieferungs-ID.

Verifizieren Sie die Signatur, bevor Sie auf eine Payload reagieren. Berechnen Sie das gleiche HMAC über die rohen Body-Bytes und vergleichen Sie mit einem Constant-Time-Vergleich statt String-Gleichheit.

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).end();
}

Einen Webhook testen

Jede Webhook-Zeile hat Send test delivery. Dies sendet eine echte Auslieferung an Ihren Endpunkt sofort und meldet den HTTP-Code, den er zurück erhielt, oder die Fehlerdetails.

Verwenden Sie dies direkt nach dem Hinzufügen eines Webhooks, bevor Sie sich darauf verlassen. Eine Firewall-Regel oder Route, die nur GET akzeptiert, ist jetzt viel leichter zu finden als während eines Vorfalls.

Auslieferungsverlauf

Jede Zeile enthält ein Sparkbar der letzten sieben Tage mit Auslieferungsanzahl, Erfolgsprozentsatz und durchschnittlicher Dauer, plus Zeitpunkt und Ergebnis der letzten Auslieferung.

Erweitern Sie Show delivery history für die einzelnen Auslieferungen: das Ereignis, der Antwortcode, die Dauer und der Fehlertext, falls vorhanden. Jede Auslieferung kann mit Retry delivery erneut gesendet werden, das den Code meldet, den es erhielt.

Auslieferungen lösen nach zwölf Sekunden aus. Wenn Ihr Endpunkt langsame Arbeit leistet, bestätigen Sie zuerst mit 200 und verarbeiten Sie danach asynchron, anstatt die Verbindung offen zu halten.

Das Secret rotieren

Klicken Sie auf Rotate secret. Das neue Secret wird einmalig angezeigt, und der Tooltip zeigt explizit, dass das alte Secret sofort ungültig wird.

Das bedeutet ein kurzes Zeitfenster, in dem Auslieferungen mit einem Secret signiert werden, das Ihr Endpunkt nicht kennt. Planen Sie dafür ein: Rotieren Sie in einem ruhigen Moment, und aktualisieren Sie Ihren Endpunkt als sehr nächste Aktion.

Rotieren Sie, wenn jemand mit Zugriff auf das Secret geht, oder wenn es jemals in einen gemeinsamen Kanal oder ein Ticket eingefügt wurde.

Deaktivieren und Löschen

Disable webhook stoppt Auslieferungen, behält aber die Konfiguration und den Verlauf, und die Zeile zeigt ein Disabled-Badge. Das ist die richtige Wahl, wenn Sie Alerts pausieren, etwa während einer geplanten Migration, die viel Rauschen verursachen wird.

Delete webhook entfernt es ganz. Verwenden Sie Deaktivieren, wenn Sie sich nicht sicher sind.

Andere Möglichkeiten, benachrichtigt zu werden

Webhooks sind die flexible Option. Zwei leichtere Alternativen befinden sich in Settings:

• Deploy email notifications, mit drei Einstellungen: alle Bereitstellungen, nur Fehler oder aus.
• Notification channels, die bei Bereitstellungserfolg oder -fehler auf eine Webhook-URL posten, Build-Regressionserkennung und Bundle-Regressionserkennung mit jeweils eigener Auslieferungsverlauf und Test-Schaltfläche.

Siehe Orbit Project Settings für beide.

Fehlerbehebung

Auslieferungen zeigen Fehler mit HTTP-Code an. Ihr Endpunkt hat einen Fehler zurückgegeben. Der Code sagt Ihnen welchen: 404 bedeutet, der Pfad ist falsch, 401 oder 403 bedeutet normalerweise, dass Ihre eigene Signaturprüfung ihn ablehnt, und 500 bedeutet, dass Ihr Handler eine Exception geworfen hat.

Auslieferungen schlagen mit Timeout fehl. Ihr Endpunkt dauerte länger als zwölf Sekunden. Geben Sie sofort 200 zurück und führen Sie die Arbeit asynchron durch.

Nichts wird überhaupt geliefert. Überprüfen Sie, dass der Webhook aktiviert ist und dass das erwartete Ereignis aktiviert ist. Ein Build, der niemals in die Warteschlange gelangt ist, löst kein Queued-Ereignis aus.

Die Signatur wird niemals validiert. Fast immer das oben beschriebene Raw-Body-Problem. Protokollieren Sie die genauen Bytes, die Sie hashen, und vergleichen Sie ihre Länge mit dem Content-Length-Header.

Eine Slack-URL wird als rohem JSON gesendet. Slack-Incoming-Webhooks befinden sich unter hooks.slack.com. Eine andere Slack-URL wird nicht als eine erkannt.

Nächste Schritte

• Bereitstellungen über Deploy Hooks auslösen für die eingehende Richtung.
• Orbit Project Settings für E-Mail-Benachrichtigungen und Benachrichtigungskanäle.
• Orbit Status Page um Ihre Kunden, nicht nur Ihr Team, zu informieren.