Webhook de rewards

Cuando un usuario completa una misión y se entrega un reward, BehaviorOS puede invocar tu endpoint vía HTTP con el detalle de lo entregado para que reacciones (entregar el producto, actualizar saldos, etc.).

Endpoints disponibles

GET    /webhooks/rewards        ← consultar la configuración actual
PUT    /webhooks/rewards        ← cargar / actualizar la configuración
POST   /webhooks/rewards/test   ← disparar un evento de prueba
DELETE /webhooks/rewards        ← eliminar la configuración (detiene envíos)

Todos están documentados en el Swagger. Requieren Authorization: Bearer <token> de tu client admin.

Configurarlo en el Control Center

1. Entrá al Control Center → Webhooks → Notificación de rewards.
2. Completá:
   • URL del webhook — endpoint público de tu sistema. Tiene que ser una URL válida con protocolo (https://...).
   • Método HTTP — POST, PUT, PATCH o DELETE. El default es POST y es lo más común.
   • Autenticación — ver modos de autenticación.
3. Guardar configuración — el badge superior pasa a Configurado.
4. Probar webhook — disparás un evento sintético contra tu endpoint para verificar conectividad y auth antes de ir a producción.

Si querés detener los envíos, Eliminar configuración desde la misma pantalla.

Cuándo se dispara

El webhook se invoca cuando se entrega el bono de completitud de una campaña. Se dispara igual por los tres caminos que pueden cerrarla: el envío sincrónico de un evento, el asincrónico, y el reclamo explícito. Si la entrega incluye varios items, el body es un array con todos en una sola request.

Request

• Method: el que configuraste (POST por default).
• URL: la que configuraste. Si elegiste auth por Query param, se agrega automáticamente.
• Headers: Content-Type: application/json + el header de auth si configuraste HEADER. El detalle exacto de qué llega según el modo de auth está en Modos de autenticación.
• Body: array JSON. Cada item es un reward entregado.

Body — ejemplo

[
  {
    "accountId": "a1b2c3d4-e5f6-47h8-89j0-k1l2m3n4o5p6",
    "type": "PRODUCTS",
    "amount": 1,
    "productId": "f7b3b2b0-4b7b-4b7b-8b7b-4b7b7b7b7b7b",
    "codes": [
      {
        "code": "ABCD-1234-EFGH",
        "item": {
          "id": "9c2a3d61-1111-2222-3333-aaaabbbbcccc",
          "name": "Xbox Game Pass 1 Month"
        }
      }
    ],
    "rewardId": "ffffffff-1111-2222-3333-444444444444",
    "campaignId": "7c1e4a90-3b22-4d51-a0f8-2e9c6b1d4a55",
    "assignmentId": "11111111-2222-3333-4444-555555555555",
    "assignment": {
      "id": "11111111-2222-3333-4444-555555555555",
      "progress": 10,
      "target": 10,
      "status": "COMPLETED",
      "missionId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "accountId": "a1b2c3d4-e5f6-47h8-89j0-k1l2m3n4o5p6",
      "rewardId": "ffffffff-1111-2222-3333-444444444444"
    },
    "productRedemptions": [
      {
        "product": {
          "id": "f7b3b2b0-4b7b-4b7b-8b7b-4b7b7b7b7b7b",
          "name": "Xbox Game Pass 1 Month"
        },
        "account": {
          "id": "a1b2c3d4-e5f6-47h8-89j0-k1l2m3n4o5p6",
          "email": "user@example.com"
        },
        "redeemables": [
          {
            "id": "redeemable-id",
            "code": "ABCD-1234-EFGH",
            "itemId": "9c2a3d61-1111-2222-3333-aaaabbbbcccc"
          }
        ]
      }
    ]
  }
]

Campos del payload

Eventos de prueba

Cuando disparás una prueba con POST /webhooks/rewards/test (o desde el botón "Probar webhook" del Control Center), recibís el mismo shape de payload pero cada item del array lleva un campo extra "test": true:

[
  {
    "accountId": "00000000-0000-0000-0000-000000000000",
    "type": "PRODUCTS",
    "amount": 1,
    ...
    "test": true
  }
]

Buenas prácticas

• Respondé en menos de 5 segundos. No es una recomendación: pasado ese tiempo BehaviorOS corta la espera. La recompensa ya quedó entregada igual, pero el aviso se pierde. Si el procesamiento es pesado, encolá en background y devolvé 200 enseguida.
• Validá la auth antes de procesar el body — si configuraste Header o Query param, chequeá el valor primero.
• Asumí duplicados y desorden — deduplicá con campaignId + accountId, que siempre vienen. assignmentId no sirve como clave: es opcional. Ver garantías de entrega.
• No esperes reintentos — el envío es best-effort sin reintentos. Reconciliá con un GET periódico contra la API si necesitás cobertura total.
• Loggeá los webhooks recibidos para debugging.