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 después de que un usuario completa una misión y se entregan los rewards correspondientes. Si una misión entrega varios items, el body es un array con todos los items 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"
        }
      }
    ],
    "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é rápido — idealmente menos de 5s. 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á usando los IDs del payload (assignmentId, productId, codes[].code). Ver garantías de entrega para el detalle.
• 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.