Webhooks de Orbit

Los webhooks envían un HTTP POST firmado a una URL de tu elección cada vez que un despliegue cambia de estado, para que tu equipo se entere de una compilación fallida en el canal que ya monitorea en lugar de enterarse por un cliente.

Dónde viven los webhooks

Abre Orbit, haz clic en el proyecto y elige Webhooks bajo el grupo Configure en la pestaña del proyecto. La página se titula Webhooks y se describe a sí misma como receptora de notificaciones HTTP POST cuando los despliegues cambian de estado, con soporte para Slack, Discord y JSON genérico.

Agregar un webhook

1. En la tarjeta Add a webhook, dale una Label. Algo como el destino al que publica.
2. Pega la URL. Debe comenzar con https://.
3. Bajo Trigger on, marca los eventos que deseas.
4. Haz clic en Add webhook.

El secreto de firma se muestra una sola vez, inmediatamente después de la creación, con una advertencia de que no se mostrará de nuevo. Cópialo antes de navegar lejos.

Un proyecto puede contener hasta diez webhooks. Agregar un undécimo se rechaza con un mensaje que nombra el límite.

Los cinco eventos

Elige deliberadamente. Suscribirse a los cinco en un proyecto ocupado convierte un canal de alerta útil en ruido que todos silencian. Para la mayoría de los equipos, Failed solo es el punto de partida correcto, con Succeeded agregado solo donde una notificación de despliegue es genuinamente útil, como un canal de producción.

Slack y Discord

Si la URL es un webhook entrante de Slack o un webhook de Discord, Orbit lo detecta desde la URL y envía un mensaje formateado en lugar de JSON sin procesar. La página lo dice bajo el campo URL: las URLs de Slack y Discord se detectan automáticamente.

El mensaje formateado lleva el nombre del proyecto, el evento, la rama, el commit corto, el tiempo de compilación, la URL desplegada y el texto de error cuando algo falló. El color sigue al evento, por lo que una tarjeta roja en el canal significa un fallo sin que nadie la lea.

No se necesita nada más. Crea el webhook entrante en Slack o Discord, pega la URL aquí, elige tus eventos, y habrás terminado.

Cargas JSON genéricas

Cualquier otra URL recibe un cuerpo JSON. Los campos son:

Usa deliveryId para hacer que tu endpoint sea idempotente. Si reintentas una entrega, o un hipo de red causa una duplicación, el id te permite reconocer que ya lo has manejado.

Verificar la firma

Cada entrega lleva tres encabezados:

• X-Orbit-Signature-256, un HMAC-SHA256 del cuerpo de la solicitud exacta usando tu secreto de firma, formateado como sha256= seguido del resumen hexadecimal.
• X-Orbit-Event, el nombre del evento.
• X-Orbit-Delivery, el id de entrega.

Verifica la firma antes de actuar sobre una carga. Calcula el mismo HMAC sobre los bytes del cuerpo sin procesar y compara usando una comparación de tiempo constante en lugar de igualdad de cadenas.

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

Probar un webhook

Cada fila de webhook tiene Send test delivery. Dispara una entrega real a tu endpoint inmediatamente e informa el código HTTP que obtuvo, o el detalle del fallo.

Úsalo justo después de agregar un webhook, antes de que confíes en él. Una regla de firewall o una ruta que solo acepta GET es mucho más fácil de encontrar ahora que durante un incidente.

Historial de entregas

Cada fila lleva una barra sparkline de los últimos siete días con el recuento de entregas, porcentaje de éxito y duración promedio, más la última hora de disparo y su resultado.

Expande Show delivery history para las entregas individuales: el evento, el código de respuesta, la duración y el texto de error donde hubo uno. Cualquier entrega se puede reenviar con Retry delivery, que informa el código que recibió.

Las entregas se agotaron después de doce segundos. Si tu endpoint hace trabajo lento, reconoce con un 200 primero y procesa después, en lugar de mantener la conexión abierta.

Rotar el secreto

Haz clic en Rotate secret. El nuevo secreto se muestra una sola vez, y la información es explícita en que el secreto anterior se vuelve inválido inmediatamente.

Eso significa una ventana corta donde las entregas se firman con un secreto que tu endpoint no conoce. Planifica para ello: rota en un momento tranquilo y actualiza tu endpoint como la siguiente acción.

Rota cuando alguien con acceso al secreto se va, o si alguna vez se ha pegado en un canal compartido o en un ticket.

Desabilitar y eliminar

Disable webhook detiene las entregas pero mantiene la configuración y el historial, y la fila muestra una insignia Disabled. Esa es la opción correcta cuando estás pausando alertas, por ejemplo durante una migración planificada que producirá mucho ruido.

Delete webhook lo elimina completamente. Usa desabilitar a menos que estés seguro.

Otras formas de ser notificado

Los webhooks son la opción flexible. Dos alternativas más ligeras se encuentran en Settings:

• Deploy email notifications, con tres configuraciones: todos los despliegues, solo fallos, o desactivado.
• Notification channels, que se publican en una URL de webhook en caso de éxito o fallo del despliegue, regresiones de compilación y regresiones de paquete, con su propio historial de entregas y botón de prueba.

Consulta Orbit Project Settings para ambos.

Solución de problemas

Las entregas se muestran como fallidas con un código HTTP. Tu endpoint devolvió un error. El código te dice cuál: 404 significa que la ruta es incorrecta, 401 o 403 suele significar que tu propia verificación de firma la está rechazando, y 500 significa que tu manejador lanzó.

Las entregas fallan con un tiempo de espera. Tu endpoint tardó más de doce segundos. Devuelve 200 inmediatamente y haz el trabajo de forma asincrónica.

Nada se entrega en absoluto. Verifica que el webhook esté habilitado y que el evento que esperabas esté marcado. Una compilación que nunca se puso en cola no dispara un evento en cola.

La firma nunca se valida. Casi siempre el problema de cuerpo sin procesar descrito arriba. Registra los bytes exactos que estás procesando y compara su longitud con el encabezado Content-Length.

Una URL de Slack se envía como JSON sin procesar. Los webhooks entrantes de Slack se encuentran bajo hooks.slack.com. Una URL de Slack diferente no será detectada como una.

A dónde ir a continuación

• Triggering Deployments Via Deploy Hooks para la dirección entrante.
• Orbit Project Settings para notificaciones de correo electrónico y canales de notificación.
• Orbit Status Page para decirle a tus clientes, no solo a tu equipo.