Crear mi primera campaña
Menú de la documentación
API

Webhooks

Recibe avisos firmados en tu servidor: cómo crear el endpoint, verificar la firma y manejar reintentos.

Un webhook es una dirección de tu servidor a la que BannerMotion envía una petición POST firmada cuando pasa algo importante. Hay 13 eventos y los 13 se emiten hoy. Los webhooks están en los planes Equipo, Agencia y Empresa.

Crear un webhook

  1. En Integraciones y API, pulsa Agregar endpoint y escribe la Dirección (URL) de tu servidor (solo el Propietario y las personas Admin).
  2. Marca los Eventos que quieres recibir y pulsa Crear endpoint.
  3. Copia el secreto (whsec_…) y pulsa Ya lo guardé. Solo se muestra una vez.
  4. En el menú del endpoint, elige Enviar evento de prueba para comprobar que llega. Recibirás un webhook.test firmado que no cuenta para la pausa.

Puedes tener hasta 10 webhooks por workspace.

Direcciones permitidas

Por seguridad solo se aceptan direcciones http o https públicas, sin usuario ni contraseña. Se rechazan las que apuntan a redes privadas, locales o de metadatos, y se vuelve a comprobar al conectar.

Qué recibe tu servidor

Cada evento llega como un POST con cuerpo JSON { id, event, createdAt, data }. El id es el del evento (evt_…) y es el mismo en todos los reintentos de esa entrega.

EncabezadoQué es
webhook-id
El id del mensaje (evt_…), igual en los reintentos.
webhook-timestamp
Segundos Unix del envío.
webhook-signature
La firma Standard Webhooks: v1, seguido del HMAC-SHA256 en base64. Durante una rotación del secreto llegan dos firmas separadas por un espacio.
X-BM-Event
El nombre del evento, por ejemplo banner.generated.
X-BM-Delivery
El id único de esta entrega (dlv_…).
X-BM-Signature
Firma anterior, por compatibilidad: sha256= y el HMAC en hexadecimal. Se mantiene un tiempo; en integraciones nuevas usa webhook-signature.

Verificar la firma

Firmamos con el estándar Standard Webhooks (standardwebhooks.com), así que sirve cualquiera de sus librerías. La firma es v1, y el HMAC-SHA256, en base64, de webhook-id, un punto, webhook-timestamp, un punto y el cuerpo exacto que recibes. La clave son los bytes del base64 que sigue a whsec_ en el secreto de tu webhook.

  1. Toma el cuerpo tal cual, antes de convertirlo a JSON.
  2. Rechaza la petición si webhook-timestamp difiere más de 5 minutos de tu reloj.
  3. Calcula la firma esperada y compárala en tiempo constante con cada firma v1,… del encabezado.
  4. Descarta los eventos repetidos por su id.

Los SDK traen verifyWebhook / verify_webhook listos. Sin SDK, usa el código de la derecha.

Rotar el secreto

En el menú del endpoint, Rotar secreto crea uno nuevo (se muestra una sola vez). Durante 24 horas cada entrega lleva dos firmas, la del secreto nuevo y la del anterior, para que cambies tu servidor sin perder eventos. Pasa los dos secretos al verificar mientras dure la rotación.

Reintentos y pausa

  • Hasta 3 intentos por envío.
  • Esperas de 5 y 30 segundos entre intentos.
  • Cada intento espera tu respuesta hasta 8 segundos.
  • Una redirección (3xx) cuenta como fallo: no se siguen.
  • Tras 5 fallos seguidos, el webhook se pausa solo y deja de recibir eventos hasta que lo reactives.
Atención. Responde con un código 2xx lo antes posible y procesa el evento después. Como una entrega puede repetirse, identifica cada evento por su id y trata los repetidos como ya procesados.

Las entregas que agotaron los intentos se pueden reintentar a mano con Reintentar, en Entregas recientes.

Eventos de webhooksLos 13 eventos, todos emitidos hoy: cuándo salen, qué trae el campo data y un ejemplo de cada uno.SDK y OpenAPIClientes de TypeScript y Python, la especificación OpenAPI 3.1 y el llms.txt de la API.
¿Te sirvió esta página?