Webhooks

Solicitud

Qué llega a tu URL cuando se dispara un evento — encabezados, campos y ejemplos.

Formato de la solicitud

Todas las entregas son POST con cuerpo JSON (UTF-8). Dos encabezados identifican la entrega; el token de autenticación va dentro del JSON.

POST

POST https://sua-api.com/alocis/webhooks
Content-Type: application/json
X-Webhook-Id: whdlv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Webhook-Event: TRANSACTION_PAID

Encabezado	Descripción
`X-Webhook-Id`	ID de entrega (whdlv_…). Úsalo para idempotencia en tu lado.
`X-Webhook-Event`	Nombre del evento, igual al campo type del JSON.
`token` (no JSON)	Token de la cuenta (whtok_…). Compáralo con el valor del panel antes de procesar.

La prueba de URL (creación o cambio de dirección) expira en 10 s. Las entregas de eventos reales usan timeout de 30 s por intento.

Sobre del payload

Todos los eventos comparten la misma estructura. Los campos nulos se omiten del JSON para reducir tamaño.

TRANSACTION_PAID

{
  "id": "whdlv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "TRANSACTION_PAID",
  "createdAt": "2026-01-15T14:22:11.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "transaction": {
      "id": "txn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "PAID",
      "amount": 9900,
      "currency": "BRL",
      "paymentMethod": "PIX"
    },
    "products": [{ "id": "prd_xxx", "name": "Curso completo" }],
    "customer": {
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "+5511999999999"
    }
  }
}

El objeto data reúne el contexto del hecho. Los campos opcionales dependen del tipo de evento:

Campo	Descripción
`data.transaction`	Transacción afectada (id, status, amount en centavos, currency, paymentMethod).
`data.subscription`	Suscripción e ítems; en cambios, billingDayChange, cycleChange, itemsChange o scheduledFor.
`data.pix` / `data.boleto`	Solo en TRANSACTION_AWAITING_PAYMENT: código Pix o URL/línea del boleto.
`data.refundRequest`	Solo en TRANSACTION_REFUND_REQUESTED: solicitud del comprador en el portal del comprador.
`data.abandonedCart`	Solo en ABANDONED_CART: productos, bumps seleccionados y datos capturados en el checkout.

Ejemplos por tipo de evento

Los datos siguientes son simulados pero con el formato real. Los campos que no aplican al evento no aparecen en el JSON.

Evento de verificación

endpoint.test

{
  "id": "whurl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "endpoint.test",
  "createdAt": "2026-01-15T14:20:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "ok": true }
}

SUBSCRIPTION_CREATED

Assinatura

{
  "id": "whdlv_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "type": "SUBSCRIPTION_CREATED",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "subscription": {
      "id": "sub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "ACTIVE",
      "billingInterval": "MONTHLY",
      "billingDay": 10,
      "items": [{ "productId": "prd_xxx", "name": "Plano Pro", "quantity": 1, "amount": 4900 }]
    },
    "customer": { "name": "João Souza", "email": "[email protected]" },
    "products": [{ "id": "prd_xxx", "name": "Plano Pro" }]
  }
}

ABANDONED_CART

Carrinho

{
  "id": "whdlv_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
  "type": "ABANDONED_CART",
  "createdAt": "2026-02-10T18:45:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "abandonedCart": {
      "products": [{ "id": "prd_aaa", "name": "E-book" }],
      "capturedEmail": "[email protected]"
    },
    "products": [{ "id": "prd_aaa", "name": "E-book" }]
  }
}

Catálogo de eventos

Registra solo los eventos que tu integración necesita. Los nombres son estables y en SCREAMING_SNAKE_CASE.

Transacciones

Evento	Cuándo se dispara
`TRANSACTION_PAID`	Transacción confirmada como pagada.
`TRANSACTION_FAILED`	Pago rechazado o fallido (excepto expiración de Pix/boleto).
`TRANSACTION_EXPIRED`	Pix o boleto expiró sin confirmación.
`TRANSACTION_AWAITING_PAYMENT`	Pix o boleto generado, aguardando pago (incluye datos de pago en data).
`TRANSACTION_REFUNDED`	Reembolso total o parcial completado por el merchant.
`TRANSACTION_REFUND_REQUESTED`	Comprador solicitó reembolso en el portal del comprador (aún no procesado por el merchant).
`TRANSACTION_CHARGEBACK`	Chargeback confirmado.
`TRANSACTION_CHARGEBACK_REQUESTED`	Disputa o chargeback en curso.

Suscripciones

Evento	Cuándo se dispara
`SUBSCRIPTION_CREATED`	Nueva suscripción creada.
`SUBSCRIPTION_BILLING_DAY_CHANGED`	Día de cobro cambiado.
`SUBSCRIPTION_CYCLE_CHANGED`	Intervalo de cobro cambiado.
`SUBSCRIPTION_ITEMS_CHANGED`	Ítems de la suscripción cambiados.
`SUBSCRIPTION_CANCELLED`	Suscripción cancelada de forma efectiva.
`SUBSCRIPTION_PAST_DUE`	Suscripción en mora.
`SUBSCRIPTION_REGULARIZED`	Suscripción regularizada tras mora.
`SUBSCRIPTION_CANCELLATION_SCHEDULED`	Cancelación programada para fin de período.
`SUBSCRIPTION_ITEMS_CHANGE_SCHEDULED`	Cambio de ítems programado para fecha futura.

Checkout

Evento	Cuándo se dispara
`ABANDONED_CART`	Comprador abandonó el checkout (datos capturados y productos seleccionados).

Orden entre eventos

Un mismo checkout puede generar varios eventos (p. ej. pago y suscripción creada). Cada uno es una entrega separada — el orden de llegada no está garantizado.