Webhooks do Orbit

Webhooks enviam um HTTP POST assinado para um URL à sua escolha sempre que uma implementação muda de estado, para que a sua equipa saiba sobre uma compilação falhada no canal que já acompanha em vez de ficar a saber por um cliente.

Onde Webhooks Vivem

Abra Orbit, clique no projeto e escolha Webhooks sob o grupo Configure na fita de abas do projeto. A página tem o título Webhooks e descreve-se como recebendo notificações HTTP POST quando as implementações mudam de estado, com suporte para Slack, Discord e JSON genérico.

Adicionar um Webhook

1. No cartão Add a webhook, dê-lhe um Label. Algo como o destino para o qual envia.
2. Cole o URL. Deve começar com https://.
3. Sob Trigger on, marque os eventos que quer.
4. Clique em Add webhook.

O segredo de assinatura é mostrado uma vez, imediatamente após a criação, com um aviso de que não será mostrado novamente. Copie-o antes de navegar para longe.

Um projeto pode conter até dez webhooks. Adicionar um décimo primeiro é recusado com uma mensagem que nomeia o limite.

Os Cinco Eventos

Escolha deliberadamente. Subscrever aos cinco em um projeto ocupado transforma um canal de alerta útil em ruído que todos silenciam. Para a maioria das equipas, Failed sozinho é o ponto de partida certo, com Succeeded adicionado apenas onde uma notificação de implementação é genuinamente útil, como um canal de produção.

Slack e Discord

Se o URL for um webhook de entrada Slack ou um webhook Discord, Orbit detecta-o a partir do URL e envia uma mensagem formatada em vez de JSON raw. A página diz assim sob o campo URL: os URLs Slack e Discord são detectados automaticamente.

A mensagem formatada transporta o nome do projeto, o evento, a branch, o commit curto, o tempo de compilação, o URL implementado e o texto de erro quando algo falhou. A cor segue o evento, portanto um cartão vermelho no canal significa uma falha sem que ninguém tenha de ler.

Nada mais é necessário. Crie o webhook de entrada no Slack ou Discord, cole o URL aqui, escolha os seus eventos e está terminado.

Payloads JSON Genéricos

Qualquer outro URL recebe um corpo JSON. Os campos são:

Use deliveryId para tornar o seu endpoint idempotente. Se retentar uma entrega, ou um soluço de rede causa uma duplicata, o id permite-lhe reconhecer que já tratou disso.

Verificar a Assinatura

Cada entrega transporta três cabeçalhos:

• X-Orbit-Signature-256, um HMAC-SHA256 do corpo exato do pedido usando o seu segredo de assinatura, formatado como sha256= seguido pelo digest hex.
• X-Orbit-Event, o nome do evento.
• X-Orbit-Delivery, o id de entrega.

Verifique a assinatura antes de agir sobre um payload. Calcule o mesmo HMAC sobre os bytes do corpo raw e compare usando uma comparação de tempo constante em vez de igualdade de string.

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

Testar um Webhook

Cada linha de webhook tem Send test delivery. Dispara uma entrega real para o seu endpoint imediatamente e relata o código HTTP que recebeu, ou o detalhe da falha.

Use-o logo após adicionar um webhook, antes de confiar nele. Uma regra de firewall ou uma rota que aceita apenas GET é muito mais fácil de encontrar agora do que durante um incidente.

Histórico de Entrega

Cada linha transporta uma sparkbar dos últimos sete dias com a contagem de entregas, percentagem de sucesso e duração média, mais a última hora de disparo e o seu resultado.

Expanda Show delivery history para as entregas individuais: o evento, o código de resposta, a duração e o texto de erro onde houve um. Qualquer entrega pode ser reenviada com Retry delivery, que relata o código que recebeu.

As entregas expiram após doze segundos. Se o seu endpoint faz trabalho lento, reconheça com um 200 primeiro e processe depois, em vez de manter a ligação aberta.

Rodar o Segredo

Clique em Rotate secret. O novo segredo é exibido uma vez, e a dica de ferramenta é explícita de que o segredo antigo se torna inválido imediatamente.

Isso significa uma janela curta onde as entregas são assinadas com um segredo que o seu endpoint não conhece. Planeje para isso: rode em um momento tranquilo e atualize o seu endpoint como a ação muito seguinte.

Rode quando alguém com acesso ao segredo sair, ou se foi alguma vez colado num canal partilhado ou num ticket.

Desativar e Eliminar

Disable webhook para as entregas, mas mantém a configuração e o histórico, e a linha mostra um badge Disabled. Esta é a escolha correta quando está a fazer uma pausa nos alertas, por exemplo durante uma migração planeada que produzirá muito ruído.

Delete webhook remove-o completamente. Use desativar a menos que tenha a certeza.

Outras Formas de Ser Notificado

Webhooks são a opção flexível. Duas alternativas mais leves ficam em Settings:

• Deploy email notifications, com três configurações: todas as implementações, apenas falhas ou desligado.
• Notification channels, que enviam para um URL de webhook em caso de sucesso ou falha de implementação, regressões de compilação e regressões de bundle, com o seu próprio histórico de entrega e botão de teste.

Ver Orbit Project Settings para ambos.

Resolução de Problemas

As entregas mostram como falhadas com um código HTTP. O seu endpoint devolveu um erro. O código diz-lhe qual: 404 significa que o caminho está errado, 401 ou 403 geralmente significa que a sua própria verificação de assinatura está a rejeitá-lo, e 500 significa que o seu handler lançou.

As entregas falham com um timeout. O seu endpoint demorou mais de doze segundos. Devolva 200 imediatamente e faça o trabalho de forma assincrónica.

Nada é entregue. Verifique se o webhook está ativado e se o evento que esperava está marcado. Uma compilação que nunca enfileirou não dispara um evento de fila.

A assinatura nunca valida. Quase sempre o problema de corpo raw descrito acima. Registe os bytes exatos que está a codificar e compare o seu comprimento com o cabeçalho Content-Length.

Um URL Slack está sendo enviado JSON raw. Os webhooks de entrada Slack vivem sob hooks.slack.com. Um URL Slack diferente não será detectado como um.

Onde Ir Depois

• Triggering Deployments Via Deploy Hooks para a direção de entrada.
• Orbit Project Settings para notificações por email e canais de notificação.
• Orbit Status Page para informar os seus clientes, não apenas a sua equipa.