Introducción
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 un reward, una publicación cambia de estado en el marketplace, etc.). En vez de que tu sistema haga polling contra nuestra API, nosotros te llamamos vía HTTP.
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.
Cómo configurarlos
- Entrá al Control Center → módulo Webhooks.
- Vas a ver una lista con todos los tipos de webhook disponibles y su estado actual (Configurado / No configurado).
- Hacé click en el que querés configurar y vas a la pantalla de detalle.
- Cargás endpoint, método y autenticación → Guardar configuración.
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 }.
En tu receptor: si el campo test del payload viene en true, no apliques efectos secundarios (no invalides cache, no escribas en DB, no notifiques usuarios). Tratalo solo como verificación de conectividad y autenticación. Los eventos reales no traen el campo test (está ausente, no llega en false) — eso te permite distinguirlos sin ambigüedad.
// Patrón recomendado en tu endpoint
app.post('/uin/webhook', (req, res) => {
if (req.body.test === true) {
return res.status(200).end(); // ack y nada más
}
// procesamiento normal del evento real
procesar(req.body);
res.status(200).end();
});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, devuelve204exista 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. |
Si necesitás cobertura total de eventos, complementá los webhooks con un GET periódico contra la API de UIN (por ejemplo, cada hora) y reconciliá contra tu estado.