Webhooks salientes

Los webhooks salientes envían una solicitud HTTP firmada a un endpoint que tú eliges cuando ocurre algo en un proyecto: cambia un caso de prueba, se cierra una ejecución o un defecto cambia de estado. Úsalos para publicar en un canal de chat, abrir un ticket en otra herramienta o alimentar tu propio flujo de trabajo.

Cada proyecto puede tener hasta 20 webhooks. Cada webhook tiene un endpoint, los eventos a los que se suscribe, un secreto de firma y un historial de entregas.

Antes de empezar

Crear un webhook

1. Abre el proyecto, selecciona Configuración y luego la pestaña Webhooks.
2. Selecciona Nuevo webhook.
3. Completa el formulario:
   • Nombre: cómo aparece el webhook en la lista, por ejemplo Alertas de release en Slack.
   • URL del endpoint: la dirección https:// que recibe las solicitudes.
   • Eventos: elige uno o varios. Cada evento seleccionado envía una solicitud al endpoint. Los eventos se agrupan por el elemento al que pertenecen. Activa Todos los eventos para enviar todos los eventos del catálogo, incluidos los que se añadan más adelante.
   • Secreto de firma (opcional): un secreto propio. Déjalo vacío y Probara generará uno.
   • Activado: un webhook desactivado conserva su configuración y no envía nada.
4. Selecciona Crear webhook. Probara muestra el secreto de firma una sola vez, después de guardar. Cópialo en tu receptor antes de cerrar el diálogo.

Gestionar webhooks

Cada webhook de la lista tiene estas acciones: Editar, Enviar prueba, Entregas, Activar o Desactivar, Rotar secreto y Eliminar.

• Un webhook desactivado conserva su configuración. Enviar prueba y Reenviar se rechazan hasta que lo actives.
• Eliminar detiene los eventos hacia el endpoint y borra el historial de entregas del webhook.

Reglas del endpoint

Secreto de firma

Probara firma cada solicitud con HMAC-SHA256, siguiendo la especificación Standard Webhooks. La firma viaja en el encabezado webhook-signature. La referencia para desarrolladores explica cómo verificarla.

• Un secreto que tú proporcionas tiene la forma whsec_ seguida de entre 24 y 64 bytes codificados en base64.
• Probara guarda el secreto cifrado, para poder firmar las solicitudes. Después solo muestra sus últimos cuatro caracteres, para que distingas los secretos.
• Rotar secreto crea un secreto nuevo y lo muestra una sola vez. El secreto actual deja de verificar las solicitudes en cuanto lo rotas, así que actualiza tu receptor con el nuevo secreto de inmediato.

Opciones avanzadas

Abre Avanzado para cambiar cómo se envían las solicitudes. Los valores predeterminados funcionan para la mayoría de los endpoints.

Método HTTP

POST por defecto. Elige PUT o PATCH si tu receptor lo espera.

Encabezados personalizados

Hasta 20 encabezados, por ejemplo Authorization con un token Bearer. No puedes usar los nombres que Probara define por sí mismo: Host, Content-Length, Content-Type, Transfer-Encoding, Connection, User-Agent, webhook-id, webhook-timestamp, webhook-signature, ni ningún nombre que empiece por cf-. Cada nombre puede aparecer una sola vez.

Los valores se guardan cifrados y no se vuelven a mostrar. Después de guardar, Probara muestra solo los nombres. Para conservar un valor al editar el webhook, deja su campo vacío. Al guardar se reemplaza la lista completa, así que un encabezado que quites se elimina.

Carga

• JSON estándar (la opción por defecto) envía el envoltorio JSON que describe Webhooks salientes para desarrolladores.
• Plantilla personalizada te permite escribir el cuerpo. Elige un tipo de contenido (application/json, application/x-www-form-urlencoded, application/xml o text/plain) y una plantilla de hasta 16.384 caracteres.

El cuerpo tiene un límite de 256 KiB. Si el envoltorio estándar supera ese tamaño, Probara quita primero data y después changes. Un cuerpo personalizado que supere el límite no se envía, y su entrega falla de inmediato con el error The rendered body is larger than 256 KiB.

Coloca un marcador de texto dentro de las comillas de una cadena JSON, y Probara lo escapa allí. Un marcador de texto cuya ruta no existe no inserta nada, y {{json ...}} inserta null. En una plantilla JSON, Probara comprueba al guardar que genere JSON válido.

Por ejemplo, una plantilla JSON mínima:

{
  "text": "{{type}}: {{entity.label}} ({{project.name}})"
}

• Empezar desde una plantilla rellena la plantilla para un webhook entrante de Slack, Microsoft Teams o Discord. Usa como endpoint la URL que te da la herramienta de chat. Cada preset envía el tipo de evento, la etiqueta de la entidad, el nombre del proyecto y el nombre de quien realizó la acción.

Enviar una prueba

Selecciona Enviar prueba, elige el Evento de muestra y vuelve a seleccionar Enviar prueba en el diálogo. La lista ofrece los eventos del webhook, o todos los eventos si Todos los eventos está activado, y empieza por el primero.

Probara envía un evento de muestra de inmediato, marcado como prueba en la carga (test en true). La muestra usa valores de ejemplo fijos, no los datos de tu proyecto. Hace un único intento, sin reintentos. Después, el diálogo indica si se entregó, con la respuesta o el error y la hora del envío, y el resultado también se añade al historial de entregas. Una prueba nunca cuenta para el contador de fallos, así que no puede desactivar el webhook.

Historial de entregas

Cada entrega terminada (exitosa o fallida) se conserva durante 30 días.

• Cada entrega muestra su estado (Pendiente, Exitosa o Fallida), sus intentos y su respuesta.
• Abre una entrega para ver la solicitud que Probara envió (método, URL, encabezados y cuerpo) y la respuesta: estado, encabezados y hasta 4096 bytes del cuerpo de la respuesta. Los valores de los encabezados personalizados aparecen como [redacted].
• Reenviar envía un evento otra vez como una entrega nueva, vinculada a la original. Conserva el ID y el cuerpo del evento, y usa la URL, el método y los encabezados actuales del webhook. Úsalo después de corregir un endpoint que falla. Los reenvíos cuentan para el contador de fallos, y un webhook desactivado no puede reenviar hasta que lo actives.
• La lista muestra cada webhook como Activo, Con fallos o Desactivado. Con fallos significa que el webhook está activado y tiene entregas fallidas desde su último éxito. Un webhook que Probara desactivó muestra Desactivado tras fallos.

Cuando una entrega falla

Un intento falla cuando el endpoint no responde con un estado 2xx en 10 segundos, cuando redirige o cuando Probara no puede conectarse a él. Los intentos fallidos se reintentan siete veces, y el último reintento llega al menos 10 horas y 42 minutos después del primer intento. El calendario completo está en la referencia para desarrolladores.

Probara desactiva un webhook automáticamente cuando sus últimas 5 entregas seguidas fallaron y no ha tenido ninguna entrega exitosa durante 72 horas. Si nunca ha tenido una entrega exitosa, las 72 horas se cuentan desde su creación. Se envía un correo a los propietarios y administradores de la organización con el host del endpoint, cuándo fue su última entrega exitosa y un enlace a la configuración del webhook.

Para reanudarlo, corrige el endpoint, selecciona Activar y reenvía los eventos que aún necesites. Activar el webhook reinicia el contador de fallos, pero no el plazo de 72 horas. Si la última entrega exitosa fue hace más de 72 horas, cinco entregas fallidas seguidas lo vuelven a desactivar.

Eventos que no envían nada, o envían uno solo

• Una marca masiva, un envío masivo de resultados o un informe de CI envía un único evento test_run.results_submitted para toda la acción. Una marca individual envía result.created.
• Los casos de prueba creados por una importación o por una clonación masiva no envían test_case.created.
• Reabrir una ejecución no envía ningún evento.
• Los pasos compartidos que pertenecen a la organización y no a un proyecto no envían eventos.
• Mientras el plan de la organización no incluya webhooks, los eventos se descartan y las entregas pendientes no se envían. Se envían cuando el plan vuelva a incluir webhooks.

Auditoría

Crear, modificar o eliminar un webhook, rotar su secreto y desactivarlo automáticamente quedan registrados en Actividad del workspace.

Siguientes pasos

• Para los nombres de los eventos, la carga útil y la verificación de firma, lee Webhooks salientes para desarrolladores.
• Para gestionar webhooks desde un script o un asistente de IA, consulta la API de webhooks y la referencia de herramientas MCP.

Antes de pasar a producción

• El endpoint es https:// en un dominio público.
• Tu receptor verifica webhook-signature contra el cuerpo sin procesar.
• Responde con 2xx en 10 segundos y hace el trabajo lento después de responder.
• Ignora un webhook-id que ya haya procesado.
• Enviar prueba muestra una entrega exitosa.