Webhooks

Los webhooks permiten que QA Hub notifique a sistemas externos cuando ocurren eventos clave — como la finalización de una ejecución de prueba, la resolución de un bug o la necesidad de un retest.

Eventos soportados

Evento	Se dispara cuando
test_run.completed	El estado de una ejecución cambia a COMPLETED
test_run_result.failed	Un resultado se marca como FAILED en una ejecución
bug.resolved	Un bug de Linear vinculado alcanza el estado de completado
retest.required	Un caso de prueba se marca para retest

Crear un webhook

Ve a Settings → Developer → Webhooks → Add webhook:

1. Introduce la URL del endpoint (debe ser HTTPS en producción)
2. Selecciona los eventos a los que suscribirse
3. Opcionalmente añade un secreto para verificación de firma
4. Haz clic en Save

Formato del payload

Todas las entregas de webhook comparten el mismo envelope:

{
  "event": "test_run.completed",
  "timestamp": "2026-05-13T12:00:00.000Z",
  "tenant_id": "cltenant001",
  "data": {
    // payload específico del evento
  }
}

Payload de test_run.completed

{
  "event": "test_run.completed",
  "data": {
    "run_id": "clrun001",
    "run_name": "Sprint 24 regression",
    "project_id": "clxyz123",
    "environment": "staging",
    "total": 48,
    "passed": 44,
    "failed": 3,
    "broken": 1,
    "skipped": 0
  }
}

Payload de bug.resolved

{
  "event": "bug.resolved",
  "data": {
    "bug_ticket_key": "LIN-42",
    "test_case_code": "TC-017",
    "test_case_id": "clcase017",
    "resolved_at": "2026-05-13T11:45:00.000Z"
  }
}

Verificación de firma

Cada entrega incluye un header X-QaHub-Signature:

X-QaHub-Signature: sha256=<HMAC-SHA256 codificado en hex>

Verifícalo en tu endpoint usando el secreto configurado al crear el webhook:

import crypto from 'crypto';

function verify(secret: string, payload: string, signature: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Comportamiento de reintentos

Las entregas fallidas (respuesta no-2xx o timeout) se reintentan hasta 3 veces con backoff exponencial. Tras 3 fallos, la entrega se marca como fallida y no se producen más reintentos.

Gestionar via API

Los webhooks también pueden gestionarse via la API interna (autenticada por sesión):

GET  /api/webhooks          — Listar suscripciones
POST /api/webhooks          — Crear suscripción
PATCH /api/webhooks/{id}    — Actualizar suscripción
DELETE /api/webhooks/{id}   — Eliminar suscripción