Orbit Webhooks

Webhooks sturen een ondertekend HTTP POST naar een URL naar keuze elke keer dat een deployment van status verandert, zodat uw team in het kanaal waar zij al actief zijn hoort van een mislukte build in plaats van het van een klant te vernemen.

Waar Webhooks Zich Bevinden

Open Orbit, klik op het project en kies Webhooks onder de Configure groep in de project tab strip. De pagina heet Webhooks en beschrijft zichzelf als het ontvangen van HTTP POST notificaties wanneer deployments van status veranderen, met ondersteuning voor Slack, Discord en generieke JSON.

Een Webhook Toevoegen

1. Geef het in de Add a webhook kaart een Label. Iets als de bestemming waar het naar stuurt.
2. Plak de URL. Deze moet beginnen met https://.
3. Onder Trigger on, vink de gewenste events aan.
4. Klik Add webhook.

Het ondertekeningsgeheim wordt eenmaal weergegeven, direct na creatie, met een waarschuwing dat het niet opnieuw zal worden weergegeven. Kopieer het voordat u navigeert.

Een project kan maximaal tien webhooks bevatten. Het toevoegen van een elfde wordt geweigerd met een bericht dat de limiet vermeldt.

De Vijf Events

Kies doelbewust. Het inschrijven op alle vijf op een druk project verandert een nuttige alertkanaal in ruis die iedereen dempt. Voor de meeste teams is Failed alleen het juiste startpunt, met Succeeded alleen toegevoegd waar een deploy notificatie echt nuttig is, zoals een productiekanaal.

Slack en Discord

Als de URL een Slack inkomende webhook of een Discord webhook is, detecteert Orbit dit vanuit de URL en stuurt een geformatteerd bericht in plaats van ruwe JSON. De pagina zegt dit onder het URL-veld: Slack en Discord URL's worden automatisch gedetecteerd.

Het geformatteerde bericht draagt de projectnaam, de event, de branch, de korte commit, de buildtijd, de ingezette URL en de fouttekst wanneer iets mislukt. Kleur volgt de event, dus een rode kaart in het kanaal betekent een fout zonder dat iemand deze hoeft te lezen.

Niets anders is nodig. Maak de inkomende webhook in Slack of Discord aan, plak de URL hier, kies uw events en u bent klaar.

Generieke JSON Payloads

Elke andere URL ontvangt een JSON-body. De velden zijn:

Gebruik deliveryId om uw endpoint idempotent te maken. Als u een bezorging opnieuw probeert of een netwerkonderbreking veroorzaakt een duplicaat, laat de id u herkennen dat u dit al hebt afgehandeld.

De Handtekening Verifiëren

Elke bezorging bevat drie headers:

• X-Orbit-Signature-256, een HMAC-SHA256 van de exacte request body met behulp van uw ondertekeningsgeheim, opgemaakt als sha256= gevolgd door de hex digest.
• X-Orbit-Event, de eventnaam.
• X-Orbit-Delivery, de bezorgings-id.

Verifieer de handtekening voordat u op een payload reageert. Bereken dezelfde HMAC over de raw body bytes en vergelijk met behulp van een constant-time vergelijking in plaats van string gelijkheid.

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();
}

Een Webhook Testen

Elke webhook rij heeft Send test delivery. Het stuurt een echte bezorging naar uw endpoint onmiddellijk en meldt de HTTP-code die het terug kreeg, of het faaldetail.

Gebruik het direct na het toevoegen van een webhook, voordat u erop vertrouwt. Een firewallregel of een route die alleen GET accepteert is veel gemakkelijker nu te vinden dan tijdens een incident.

Bezorgingsgeschiedenis

Elke rij bevat een sparkbar van de afgelopen zeven dagen met het aantal bezorgingen, het succespercentage en de gemiddelde duur, plus het laatste afvuurmoment en het resultaat.

Vouw Show delivery history uit voor de individuele bezorgingen: de event, de antwoordcode, de duur en de fouttekst waar deze was. Elke bezorging kan opnieuw worden verzonden met Retry delivery, die de code meldt die het terug kreeg.

Bezorgingen verlopen na twaalf seconden. Als uw endpoint traag werk doet, bevestig met een 200 eerst en verwerk daarna, in plaats van de verbinding open te houden.

Het Geheim Roteren

Klik Rotate secret. Het nieuwe geheim wordt eenmaal weergegeven en de tooltip is expliciet dat het oude geheim onmiddellijk ongeldig wordt.

Dit betekent een kort venster waarin bezorgingen worden ondertekend met een geheim dat uw endpoint niet kent. Plan ervoor: roteer op een rustig moment en werk uw endpoint bij als de volgende actie.

Roteer wanneer iemand met toegang tot het geheim vertrekt, of als het ooit in een gedeeld kanaal of ticket is geplakt.

Uitschakelen en Verwijderen

Disable webhook stopt bezorgingen maar behoudt de configuratie en geschiedenis, en de rij toont een Disabled badge. Dat is de juiste keuze wanneer u alerts pauzeer, bijvoorbeeld tijdens een geplande migratie die veel ruis zal opleveren.

Delete webhook verwijdert het volledig. Gebruik uitschakelen tenzij u zeker bent.

Andere Manieren Om Op de Hoogte Te Worden Gesteld

Webhooks zijn de flexibele optie. Twee lichtere alternatieven bevinden zich in Settings:

• Deploy email notifications, met drie instellingen: alle deployments, alleen fouten of uit.
• Notification channels, die naar een webhook URL posten bij deploy succes of falen, build regressies en bundle regressies, met hun eigen bezorgingsgeschiedenis en testknop.

Zie Orbit Project Settings voor beide.

Probleemoplossing

Bezorgingen tonen als mislukt met een HTTP-code. Uw endpoint retourneerde een fout. De code vertelt u welke: 404 betekent dat het pad onjuist is, 401 of 403 betekent meestal dat uw eigen handtekeningcontrole het weigert en 500 betekent dat uw handler een fout heeft gegooid.

Bezorgingen mislukken met een timeout. Uw endpoint duurde langer dan twaalf seconden. Return 200 onmiddellijk en doe het werk asynchroon.

Helemaal niets wordt bezorgd. Controleer of de webhook is ingeschakeld en dat de event die u verwacht is aangevinkt. Een build die nooit in de wachtrij kwam voert geen queued event uit.

De handtekening valideert nooit. Bijna altijd het raw-body probleem dat hierboven is beschreven. Log de exacte bytes die u hasht en vergelijk hun lengte met de Content-Length header.

Een Slack URL wordt verzonden als ruwe JSON. Slack inkomende webhooks bevinden zich onder hooks.slack.com. Een ander Slack URL zal niet als één worden gedetecteerd.

Waar Verder

• Triggering Deployments Via Deploy Hooks voor de inkomende richting.
• Orbit Project Settings voor e-mailmeldingen en meldingskanalen.
• Orbit Status Page om uw klanten, niet alleen uw team, in te lichten.