Webhook di Orbit

I webhooks inviano un HTTP POST firmato a un URL di tua scelta ogni volta che lo stato di una distribuzione cambia, quindi il tuo team viene informato di una build fallita nel canale che già segue invece di scoprirlo da un cliente.

Dove Si Trovano I Webhooks

Apri Orbit, fai clic sul progetto e scegli Webhooks nel gruppo Configure nella barra delle schede del progetto. La pagina è intitolata Webhooks e si descrive come ricevente di notifiche HTTP POST quando le distribuzioni cambiano stato, con supporto per Slack, Discord e JSON generico.

Aggiunta Di Un Webhook

1. Nella scheda Add a webhook, assegnagli un Label. Qualcosa come la destinazione a cui invia.
2. Incolla l'URL. Deve iniziare con https://.
3. Sotto Trigger on, spunta gli eventi che desideri.
4. Fai clic su Add webhook.

Il segreto di firma viene mostrato una sola volta, immediatamente dopo la creazione, con un avvertimento che non verrà più mostrato. Copialo prima di navigare altrove.

Un progetto può contenere fino a dieci webhooks. L'aggiunta di un undicesimo viene rifiutata con un messaggio che nomina il limite.

I Cinque Eventi

Scegli deliberatamente. L'iscrizione a tutti e cinque su un progetto attivo trasforma un canale di avviso utile in rumore che tutti disattivano. Per la maggior parte dei team, Failed da solo è il punto di partenza giusto, con Succeeded aggiunto solo dove una notifica di distribuzione è genuinamente utile, come un canale di produzione.

Slack E Discord

Se l'URL è un webhook in arrivo di Slack o un webhook di Discord, Orbit lo rileva dall'URL e invia un messaggio formattato anziché JSON grezzo. La pagina lo dice sotto il campo URL: gli URL di Slack e Discord vengono rilevati automaticamente.

Il messaggio formattato riporta il nome del progetto, l'evento, il ramo, il commit breve, il tempo di build, l'URL distribuito e il testo di errore quando qualcosa è fallito. Il colore segue l'evento, quindi una scheda rossa nel canale significa un errore senza che nessuno la legga.

Non è necessario nulla di più. Crea il webhook in arrivo in Slack o Discord, incolla l'URL qui, scegli i tuoi eventi e hai finito.

Payload JSON Generici

Qualsiasi altro URL riceve un corpo JSON. I campi sono:

Usa deliveryId per rendere il tuo endpoint idempotente. Se ripeti una consegna, o un hiccup di rete causa un duplicato, l'id ti consente di riconoscere che l'hai già gestito.

Verifica Della Firma

Ogni consegna include tre intestazioni:

• X-Orbit-Signature-256, un HMAC-SHA256 del corpo della richiesta esatta utilizzando il tuo segreto di firma, formattato come sha256= seguito dal digest esadecimale.
• X-Orbit-Event, il nome dell'evento.
• X-Orbit-Delivery, l'id della consegna.

Verifica la firma prima di agire su un payload. Calcola lo stesso HMAC sui byte del corpo grezzo e confronta utilizzando un confronto a tempo costante anziché uguaglianza tra stringhe.

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

Test Di Un Webhook

Ogni riga di webhook ha Send test delivery. Attiva una consegna reale al tuo endpoint immediatamente e segnala il codice HTTP che ha ricevuto, o il dettaglio dell'errore.

Usalo subito dopo aver aggiunto un webhook, prima di affidarci. Una regola del firewall o una route che accetta solo GET è molto più facile da trovare ora che durante un incidente.

Cronologia Delle Consegne

Ogni riga contiene una sparkbar degli ultimi sette giorni con il conteggio delle consegne, la percentuale di successo e la durata media, più l'ultimo orario di attivazione e il suo risultato.

Espandi Show delivery history per le singole consegne: l'evento, il codice di risposta, la durata e il testo di errore dove ce n'è uno. Qualsiasi consegna può essere inviata nuovamente con Retry delivery, che segnala il codice che ha ricevuto.

Le consegne scadono dopo dodici secondi. Se il tuo endpoint svolge lavori lenti, riconosci con un 200 per primo e elabora successivamente, anziché mantenere la connessione aperta.

Rotazione Del Segreto

Fai clic su Rotate secret. Il nuovo segreto viene visualizzato una sola volta e il tooltip è esplicito sul fatto che il vecchio segreto diventa immediatamente non valido.

Ciò significa una breve finestra in cui le consegne sono firmate con un segreto che il tuo endpoint non conosce. Pianificalo: ruota in un momento tranquillo e aggiorna il tuo endpoint come prossima azione.

Ruota quando qualcuno con accesso al segreto se ne va, o se è stato mai incollato in un canale condiviso o in un ticket.

Disabilitazione E Eliminazione

Disable webhook interrompe le consegne ma mantiene la configurazione e la cronologia, e la riga mostra un badge Disabled. Questa è la scelta giusta quando stai sospendendo gli avvisi, ad esempio durante una migrazione pianificata che produrrà molto rumore.

Delete webhook la rimuove completamente. Usa disable a meno che non sei sicuro.

Altri Modi Per Essere Notificato

I webhooks sono l'opzione flessibile. Due alternative più leggere si trovano in Settings:

• Deploy email notifications, con tre impostazioni: tutte le distribuzioni, solo gli errori, o no.
• Notification channels, che inviano a un URL di webhook al successo o al fallimento della distribuzione, alle regressioni di build e alle regressioni di bundle, con la loro cronologia di consegna e pulsante di test.

Vedi Impostazioni Progetto Orbit per entrambi.

Risoluzione Dei Problemi

Le consegne vengono visualizzate come non riuscite con un codice HTTP. Il tuo endpoint ha restituito un errore. Il codice ti dice quale: 404 significa che il percorso è sbagliato, 401 o 403 di solito significa che il tuo controllo della firma lo sta rifiutando, e 500 significa che il tuo handler ha generato un'eccezione.

Le consegne non riescono con un timeout. Il tuo endpoint ha impiegato più di dodici secondi. Restituisci 200 immediatamente e fai il lavoro in modo asincrono.

Nulla viene consegnato affatto. Verifica che il webhook sia abilitato e che l'evento che ti aspettavi sia selezionato. Una build che non è mai stata messa in coda non attiva un evento queued.

La firma non convalida mai. Quasi sempre il problema del corpo grezzo descritto sopra. Registra i byte esatti che stai hash e confronta la loro lunghezza con l'intestazione Content-Length.

Un URL Slack viene inviato come JSON grezzo. Gli incoming webhooks Slack si trovano sotto hooks.slack.com. Un URL Slack diverso non verrà rilevato come uno.

Dove Andare Dopo

• Attivazione delle Distribuzioni Via Deploy Hooks per la direzione in entrata.
• Impostazioni Progetto Orbit per notifiche email e canali di notifica.
• Pagina Di Stato Orbit per dire ai tuoi clienti, non solo al tuo team.