Skip to main content
Un Destino es por donde salen los eventos de Brein hacia otro sistema. Le das una dirección y los tipos de evento que te importan; Brein le manda cada uno, firmado con Standard Webhooks 1.0.0, en cuanto ocurre.

Crear un Destino

Por la API, con una llave de API del dueño o de un admin del espacio.
  • Dirección: https pública, puerto 443 u 8443, hasta 2048 caracteres. No se aceptan direcciones privadas ni internas, y Brein vuelve a revisarlo en cada envío.
  • Eventos: de 1 a 12 tipos del catálogo. Se pueden cambiar después; un tipo agregado recibe solo lo que pase desde ese momento, no historia.
  • Secreto: whsec_…, se muestra una sola vez.
Un espacio de prueba no tiene Destinos: ahí nada sale de Brein.

Lo que recibes

El cuerpo es el CloudEvent completo. webhook-id es el id del evento y no cambia entre reintentos: úsalo para descartar repetidos.

Verificar la firma

Verifica antes de confiar en el cuerpo. Usa los bytes tal cual llegaron, no un JSON vuelto a serializar.
Puede venir más de una firma separada por espacio: cuando rotas el secreto, durante 24 horas Brein firma con el nuevo y con el anterior. Acepta si cualquiera coincide.

Responder y reintentos

Responde 2xx rápido y procesa después. Brein espera 10 segundos como máximo y no sigue redirecciones. Son diez intentos. Después de cada fallo espera 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h y 24 h: unas 75 horas del primero al último. Cada reintento lleva el mismo webhook-id y una firma nueva. Si las últimas cinco entregas terminadas se agotaron todas, el Destino se deshabilita. Un mismo evento puede llegar más de una vez. Así funciona Standard Webhooks: es mejor que perderlo. Descarta por webhook-id. El orden tampoco está garantizado: usa time y el subject.

Un agente que responde no se avisa a sí mismo

Un agente que recibe una entrega suele escribir de vuelta por el MCP o la API, y esa escritura puede producir un evento del mismo tipo que escucha. Para cortar el bucle, manda el id del evento que recibiste en el encabezado X-Brein-Cause de cada llamada con que respondes (en el MCP, el mismo encabezado de la petición). Brein guarda ese evento como causationid de lo que escribas y nunca entrega a tu Destino un evento cuya causa ya le entregó. Los otros Destinos sí lo reciben. Un id que no es un evento de tu espacio se rechaza con X-Brein-Cause como campo.

Tipos de evento retirados

El recorrido de una Llegada (arrival.received, .accepted, .decided, .rejected, .quarantined, .reprocessed) ya no está en el catálogo. Un Destino que estaba suscrito a uno conserva la suscripción guardada pero no recibe nada por ella, y ya no se ve en su lista; al guardar la lista de nuevo se quita. Las entregas que ya estaban en cola se envían.

Revisar, probar y reenviar

Todo por la API, con la misma llave: Las rutas empiezan con https://api.trybrein.com/api/v1/workspaces/<slug>. Brein no guarda lo que tu servidor responde, solo el código y el tiempo. Un Destino pausado guarda lo pendiente y lo envía al reanudar. El evento de ejemplo no se anota en tu libro. ¿Te pierdes algo por una caída larga? Lee el libro desde tu último cursor.