Webhooks

Request

What hits your URL when an event fires — headers, fields, and copy-paste examples.

Request format

All deliveries are POST with a UTF-8 JSON body. Two headers identify the delivery; the auth token is inside the JSON.

POST

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

Header	Description
`X-Webhook-Id`	Delivery ID (whdlv_…). Use for idempotency on your side.
`X-Webhook-Event`	Event name, same as the JSON type field.
`token` (no JSON)	Account token (whtok_…). Compare to the dashboard value before processing.

URL proof (create or URL change) times out after 10 s. Live event deliveries use a 30 s timeout per attempt.

Payload envelope

All events share the same structure. Null fields are omitted from JSON to save bandwidth.

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"
    }
  }
}

The data object carries fact context. Optional fields depend on the event type:

Field	Description
`data.transaction`	Affected transaction (id, status, amount in cents, currency, paymentMethod).
`data.subscription`	Subscription and items; on changes, billingDayChange, cycleChange, itemsChange, or scheduledFor.
`data.pix` / `data.boleto`	Only on TRANSACTION_AWAITING_PAYMENT: Pix code or boleto URL/digitable line.
`data.refundRequest`	Only on TRANSACTION_REFUND_REQUESTED: request created by the buyer in the buyer portal.
`data.abandonedCart`	Only on ABANDONED_CART: products, selected bumps, and data captured at checkout.

Examples by event type

Sample data below — same shape as production. Fields that do not apply to an event are omitted from JSON.

Verification event

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" }]
  }
}

Event catalog

Subscribe only to events your integration needs. Names are stable and use SCREAMING_SNAKE_CASE.

Transactions

Event	When it fires
`TRANSACTION_PAID`	Transaction marked as paid.
`TRANSACTION_FAILED`	Payment declined or failed (except Pix/boleto expiration).
`TRANSACTION_EXPIRED`	Pix or boleto expired without payment.
`TRANSACTION_AWAITING_PAYMENT`	Pix or boleto issued, awaiting payment (payment details in data).
`TRANSACTION_REFUNDED`	Full or partial refund completed by the merchant.
`TRANSACTION_REFUND_REQUESTED`	Buyer requested a refund via the buyer portal (not yet processed by the merchant).
`TRANSACTION_CHARGEBACK`	Chargeback confirmed.
`TRANSACTION_CHARGEBACK_REQUESTED`	Dispute or chargeback opened.

Subscriptions

Event	When it fires
`SUBSCRIPTION_CREATED`	New subscription created.
`SUBSCRIPTION_BILLING_DAY_CHANGED`	Billing day changed.
`SUBSCRIPTION_CYCLE_CHANGED`	Billing interval changed.
`SUBSCRIPTION_ITEMS_CHANGED`	Subscription items changed.
`SUBSCRIPTION_CANCELLED`	Subscription effectively canceled.
`SUBSCRIPTION_PAST_DUE`	Subscription past due.
`SUBSCRIPTION_REGULARIZED`	Subscription regularized after past due.
`SUBSCRIPTION_CANCELLATION_SCHEDULED`	Cancellation scheduled for period end.
`SUBSCRIPTION_ITEMS_CHANGE_SCHEDULED`	Item change scheduled for a future date.

Checkout

Event	When it fires
`ABANDONED_CART`	Buyer abandoned checkout (captured data and selected products).

Order between events

One checkout may emit multiple events (e.g. payment plus subscription created). Each is a separate delivery — arrival order is not guaranteed. Design for that.