Webhooks

BehaviorOS notifica eventos a tus sistemas vía HTTP — recompensas entregadas, cambios de estado de publicaciones, etc.

BehaviorOS puede avisarle a tu sistema cuando pasan cosas relevantes: un usuario completa una misión y se entrega una recompensa, una publicación cambia de estado en el marketplace. En vez de que tu sistema consulte periódicamente, nosotros te llamamos vía HTTP.

Esta página cubre el contrato: los modos de autenticación, qué llega exactamente y qué garantiza el canal. Para activarlos, ver Configuración; para construir el receptor, Recibir notificaciones.

Cada tipo de webhook se configura por separado. Podés tener prendido el de rewards y apagado el de publicaciones, o viceversa. Si no configurás un webhook, no se dispara.

Tipos disponibles

Webhook	Se dispara cuando...	Página
Notificación de rewards	Un usuario completa una misión y se entregan rewards	Ver detalles
Cambio de estado de publicación	Una publicación se publica, se despublica o se pausa por falta de stock	Ver detalles

Los dos comparten la misma forma de configurarse — endpoint, método HTTP y autenticación. Cambian el contexto en el que se disparan y el shape del payload.

Conceptos comunes a todos los webhooks

Estas características aplican igual para los dos tipos.

Modos de autenticación

Cuando configurás un webhook, elegís cómo querés que BehaviorOS se autentique contra tu endpoint. Tres modos:

`authenticationMethodType`	Campos requeridos	Qué adjunta BehaviorOS al request	Cuándo usarlo
omitido / `null`	—	Nada — sólo el body JSON	Endpoint público o protegido por otro medio (IP allowlist, secreto en la URL)
`HEADER`	`authenticationMethodKey` (nombre del header), `authenticationValue` (valor)	Un header HTTP con el key y value que configures	Standard. Lo más común: `Authorization: Bearer <secreto>` o `X-API-Key: <secreto>`
`QUERY_PARAM`	`authenticationMethodKey` (nombre del param), `authenticationValue` (valor)	Un par `?clave=valor` appendado a la URL	Casos en los que tu plataforma no permite leer headers custom

Qué va a recibir tu endpoint exactamente

Si guardás esta configuración con HEADER auth:

{
  "endpoint": "https://tu-dominio.com/uin/webhook",
  "method": "POST",
  "authenticationMethodType": "HEADER",
  "authenticationMethodKey": "X-API-Key",
  "authenticationValue": "secret123"
}

…tu endpoint recibe el siguiente request:

POST /uin/webhook HTTP/1.1
Host: tu-dominio.com
Content-Type: application/json
X-API-Key: secret123

{ ... body del evento ... }

Si en cambio configuraste QUERY_PARAM con authenticationMethodKey: "token" y authenticationValue: "abc123", el request llega como:

POST /uin/webhook?token=abc123 HTTP/1.1
Host: tu-dominio.com
Content-Type: application/json

{ ... body del evento ... }

Sin headers extra — el secreto va en la URL. El Content-Type: application/json se envía siempre, independientemente del modo de auth.

El valor de autenticación se enmascara en la UI (campo password). Tratalo como un secreto — guardalo en un secret manager y rotalo si sospechás filtración.

Probar el webhook antes de ir a producción

Después de guardar la configuración, podés disparar un evento de prueba desde el Control Center (botón "Probar webhook") o vía API (POST /webhooks/:type/test).

BehaviorOS arma un payload con la misma forma que un evento real, pero con un campo extra "test": true, y hace un POST contra el endpoint que configuraste. Si tu endpoint responde 2xx, te devolvemos { "success": true }. Si responde error (4xx, 5xx, timeout, DNS no resuelve), te devolvemos { "success": false }.

Los eventos reales no traen el campo test — está ausente, no llega en false. Eso te permite distinguirlos sin ambigüedad. Cómo tratarlo en tu endpoint está en Recibir notificaciones.

Detener los envíos

Si querés que BehaviorOS deje de mandarte un tipo de webhook, hay dos formas:

Desde el Control Center: botón rojo "Eliminar configuración" en la pantalla de detalle.
Vía API: DELETE /webhooks/:type — idempotente, devuelve 204 exista o no la config.

Apenas eliminás la configuración, BehaviorOS deja de despachar webhooks de ese tipo para tu cliente hasta que cargues una nueva con PUT.

Garantías de entrega

Aspecto	Comportamiento
Reintentos	Ninguno. Si tu endpoint falla (no responde, devuelve 5xx, hay timeout), perdés ese evento. BehaviorOS registra el error de su lado y dropea.
Orden	Sin garantía. Eventos próximos en el tiempo pueden llegar fuera de orden. Usá `timestamp` del payload, no el orden de llegada.
Duplicados	Posibles bajo concurrencia. Diseñá tu receptor para ser idempotente — usá los IDs del payload para deduplicar.
Latencia	Best-effort. El envío arranca después de que la API call que disparó el evento responde. Esperá entregas en segundos, no en milisegundos.

Ninguna de estas garantías se puede compensar desde este lado: son propiedades del canal. Lo que las absorbe es el diseño del receptor — ver Recibir notificaciones.

Webhook de rewards

Detalles, payload y configuración.

Webhook de publicaciones