Recibir notificaciones

Cómo construir el endpoint que recibe los avisos de BehaviorOS, y por qué tiene que ser idempotente

Si emitís eventos por el camino asincrónico, el resultado no vuelve en la respuesta: llega a un endpoint que exponés vos.

También podés recibir avisos de otros hechos, como el cambio de estado de una publicación. El catálogo completo y la forma de cada mensaje están en Webhooks; esta página cubre cómo construir el receptor.

Las cuatro reglas

El canal es best-effort y sin reintentos. Eso no es un detalle de implementación: es la restricción que determina cómo tenés que escribir el receptor.

1 · Respondé rápido

Idealmente en menos de 5 segundos, con 200 o 204. Si el procesamiento es pesado, encolá en background y confirmá enseguida.

Un receptor lento no solo pierde ese evento: mientras tarda, no está atendiendo los siguientes.

2 · Validá la autenticación antes de procesar

Si configuraste autenticación por header o por query param, comprobá el valor antes de tocar el body. Tu endpoint es público: cualquiera puede llamarlo.

3 · Asumí duplicados y desorden

Un mismo evento puede llegar dos veces bajo concurrencia, y dos eventos cercanos pueden llegar en orden inverso.

Deduplicá con los identificadores del propio mensaje.
Ordená por el timestamp del payload, nunca por el orden de llegada.

4 · Reconciliá

Si tu endpoint falla, el evento se pierde: no hay reintento. Pero la recompensa ya quedó entregada del lado de BehaviorOS.

Por eso un receptor solo no alcanza cuando el dato importa. Dejá un trabajo periódico que consulte my-rewards y reconcilie contra tu estado — el webhook acelera, la consulta garantiza.

Si necesitás el resultado dentro de la misma transacción, no uses este camino: usá el camino sincrónico, que devuelve el resultado en la respuesta.

El campo `test`

Desde el Control Center podés disparar un evento de prueba. Llega con la misma forma que uno real, más un campo test: true.

Los eventos reales no traen ese campo — está ausente, no llega en false. Eso te permite distinguirlos sin ambigüedad:

app.post('/uin/webhook', (req, res) => {
  if (req.body.test === true) {
    return res.status(200).end();   // acuse y nada más
  }

  procesar(req.body);
  res.status(200).end();
});

Ante un evento de prueba no apliques efectos secundarios: no entregues el producto, no toques saldos, no invalides caché, no notifiques al usuario. Es una verificación de conectividad y autenticación, nada más.

Tratá el aviso como una señal, no como la verdad

Para los webhooks que informan un cambio de estado, el patrón que resiste desorden y duplicados es no confiar en los datos del mensaje:

Recibís el aviso
   │
   ├─ extraés el identificador del recurso
   │
   ├─ consultás el recurso por API      ← la fuente de verdad
   │
   └─ actualizás tu estado con lo que devolvió

El mensaje te dice que algo cambió; la API te dice cuál es el estado actual. Si dos avisos llegan fuera de orden, los dos terminan consultando lo mismo y convergen.

Antes de producción

Endpoint publicado, accesible desde internet y con autenticación configurada.
Probado con el botón Probar webhook del Control Center.
Idempotente ante duplicados y tolerante al desorden.
Con trabajo de reconciliación corriendo.
Registrando cada mensaje recibido, para poder depurar después.

Qué sigue

Ir a producción — la lista de verificación completa.

On this page