Referencia: POST /webhooks/scm/:provider
Endpoint que recibe los webhooks de GitHub: la firma de cada entrega, las respuestas posibles y la rotación del secreto.
GitHub es el único proveedor de repositorios compatible actualmente, por lo que el parámetro :provider es github. Este endpoint no utiliza API keys: cada entrega se valida mediante el secreto HMAC configurado para la conexión del repositorio.
Encabezados y eventos
| GitHub | |
|---|---|
| Encabezado de firma | x-hub-signature-256 (formato sha256=<hex>) |
| Encabezado de evento | x-github-event: push o pull_request |
| Encabezado de id de entrega | x-github-delivery |
| Acciones de pull request manejadas | opened, synchronize |
Respuestas
| Respuesta | Significado |
|---|---|
202, { "status": "accepted" } | Firma válida. Evento almacenado y encolado para su procesamiento. |
202, { "status": "duplicate" } | El par (proveedor, id de entrega) ya fue procesado. Las entregas repetidas son idempotentes. |
202, { "status": "ignored" } | Firma válida pero tipo de evento no soportado por Qably. |
404, Unsupported provider "<value>" | El valor de :provider en la ruta no es un nombre de proveedor que Qably reconozca. Use github. |
401 | Fallo de verificación de firma contra las conexiones del repositorio. |
400 | Cuerpo de la petición inválido o JSON mal formado. |
Límite de tasa de 60 peticiones por minuto por instancia. Los eventos aceptados se procesan en segundo plano de manera asíncrona. La respuesta HTTP confirma la recepción correcta del evento, no la conclusión de su procesamiento.
Rotación del secreto
Cada conexión almacena su propio secreto HMAC. Si el secreto en el proveedor difiere del registrado en Qably, las entregas responderán con código 401. Al solicitar la rotación, Qably genera un nuevo valor, lo almacena cifrado y lo retorna en la respuesta por única vez.
| Acción | Endpoint | Rol requerido |
|---|---|---|
| Rotar el secreto del webhook | POST /projects/:projectId/repository/webhook-secret | owner o admin |
La respuesta HTTP 201 entrega el objeto { "webhookSecret": "<64 caracteres hexadecimales>" }. Este valor debe copiarse inmediatamente en la configuración del webhook en el repositorio. El secreto anterior queda invalidado al instante. Solicitar la rotación en un proyecto sin repositorio vinculado responde con código 404.
Importante: La rotación de secretos también está disponible desde la pestaña Repositorio en la consola de Qably. Durante el lapso entre la rotación y la actualización en el proveedor, las entregas entrantes fallarán con error 401 y deberán reenviarse desde el panel de entregas del proveedor.