> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Payload dos webhooks

> Formato dos POSTs que a Corvex envia para a sua URL (corvex.order.* e corvex.cart.abandoned).

Comece pela [visão geral dos webhooks](/webhooks-overview) (fluxo, eventos e requisitos). Esta página descreve o **corpo** dos POSTs JSON.

Para **criar, listar e editar** webhooks (URL, eventos, secret), use a [API v1 de webhooks](/api/v1/webhooks).

## Autenticação do POST

Se você configurou um `secret`, valide o header `X-Webhook-Signature` (HMAC-SHA256 do JSON do body):

```javascript theme={null}
const crypto = require("crypto");

function validateWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(JSON.stringify(payload));
  const expected = hmac.digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```

Headers enviados:

```http theme={null}
Content-Type: application/json
User-Agent: Corvex-Webhook/1.0
X-Webhook-Signature: <hmac-sha256>   # se houver secret
```

## Eventos (configuração → payload)

| Evento na API v1  | Campo `event` no POST    |
| ----------------- | ------------------------ |
| `ORDER_CREATED`   | `corvex.order.created`   |
| `ORDER_PAID`      | `corvex.order.paid`      |
| `ORDER_CANCELLED` | `corvex.order.cancelled` |
| `ORDER_REFUNDED`  | `corvex.order.refunded`  |
| `CART_ABANDONED`  | `corvex.cart.abandoned`  |

`corvex.order.pending` é interno e **não** é enviado a endpoints de lojistas.

## Pedidos — exemplo completo (`corvex.order.paid`)

Valores em **reais** (decimal), não centavos. Dados fictícios; na prática alguns campos podem vir ausentes ou `null` — trate sempre com segurança.

```json theme={null}
{
  "id": "f7542077-5b0b-4b4a-9283-8cd16fc70b96",
  "event": "corvex.order.paid",
  "amount": 374.32,
  "status": "paid",
  "method": "pix",
  "client": {
    "doc": "CPF:52998224725",
    "name": "Ana Silva",
    "email": "ana.silva@example.com",
    "phone": "5511987654321"
  },
  "items": [
    {
      "id": "ca9715eb-1e57-462a-9266-b0ce884c2993",
      "name": "Jogo de Panelas Cookover 9 Peças",
      "price": 274.32,
      "quantity": 1,
      "externalRef": "05da5a8d-6347-4c7c-a784-cc3a2fdafa05",
      "orderBump": false,
      "gift": false
    },
    {
      "id": "b8e2a1c0-9f3d-4e5a-b6c7-d8e9f0a1b2c3",
      "name": "Garantia estendida 12 meses",
      "price": 100.0,
      "quantity": 1,
      "externalRef": "bump-garantia-456",
      "orderBump": true,
      "gift": false
    }
  ],
  "address": {
    "city": "São José do Rio Preto",
    "state": "SP",
    "number": "165",
    "street": "Rua Alcides Cardoso Treme",
    "zipcode": "15045464",
    "complement": "Apto 42",
    "neighborhood": "Residencial Ana Célia"
  },
  "utm": {
    "ttp": "01KET6P10HCF9EW5SBHZ6MZY7C_.tt.0",
    "ttclid": "",
    "source": "instagram",
    "medium": "cpc",
    "campaign": "lancamento-panelas",
    "content": "story-video-01",
    "term": "panelas-inducao",
    "page": {
      "url": "https://minhaloja.example.com/pay/426785fd-8140-4d43-b845-9d9005758f82",
      "referrer": "https://www.instagram.com/"
    }
  },
  "checkout_query_params": {
    "product": "panelas-cookover",
    "variant": "9-pecas",
    "cupom": "LANC10"
  },
  "timestamp": "2026-01-12T23:16:08.198Z",
  "paidAt": "2026-01-12T23:20:15.543Z",
  "pix_code": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865405374.325802BR5925Loja%20Exemplo6009SAO%20PAULO62070503***6304ABCD",
  "pageOrderDetails": "https://minhaloja.example.com/pay/426785fd-8140-4d43-b845-9d9005758f82/pix-success?payment=f7542077-5b0b-4b4a-9283-8cd16fc70b96"
}
```

Outros eventos de pedido (`corvex.order.created`, `corvex.order.cancelled`, `corvex.order.refunded`) usam a **mesma forma**; mudam `event`, `status`, `method` e campos como `paidAt` (só em `paid`).

### `status` e `method`

| `status`                     | Significado          |
| ---------------------------- | -------------------- |
| `pending`, `waiting_payment` | Aguardando pagamento |
| `paid`                       | Pago                 |
| `refused`                    | Recusado/cancelado   |
| `refunded`                   | Reembolsado          |

| `method`                             | Significado         |
| ------------------------------------ | ------------------- |
| `pix`, `card`, `bankslip`, `unknown` | Método de pagamento |

### Campos condicionais

| Campo                                     | Quando aparece                            |
| ----------------------------------------- | ----------------------------------------- |
| `paidAt`                                  | Em `corvex.order.paid`                    |
| `pix_code`                                | `method` é `pix` e há código              |
| `pageOrderDetails`                        | `method` é `pix` e loja com domínio ativo |
| `address`, `utm`, `checkout_query_params` | Quando existirem no checkout              |

`client.doc` usa `TIPO:NÚMERO` (ex.: `CPF:...`) ou `"N/A"`.

## Carrinho abandonado

Disparo após **90 segundos** de desconexão no checkout, com webhook configurado para `CART_ABANDONED`. Não dispara se o visitante voltar no prazo, se já pagou, ou sem contato mínimo **(nome + telefone)** ou **(nome + e-mail)**.

### Exemplo completo (`corvex.cart.abandoned`)

```json theme={null}
{
  "id": "426785fd-8140-4d43-b845-9d9005758f82",
  "leadId": "a8f3c2d1-9e4b-4a7c-8d6f-1b2e3c4d5e6f",
  "checkoutId": "426785fd-8140-4d43-b845-9d9005758f82",
  "event": "corvex.cart.abandoned",
  "amount": 274.32,
  "status": "abandoned",
  "url_checkout": "https://minhaloja.example.com/checkout/426785fd-8140-4d43-b845-9d9005758f82",
  "client": {
    "doc": "CPF:52998224725",
    "name": "Ana Silva",
    "email": "ana.silva@example.com",
    "phone": "5511987654321"
  },
  "items": [
    {
      "id": "ca9715eb-1e57-462a-9266-b0ce884c2993",
      "name": "Jogo de Panelas Cookover 9 Peças",
      "price": 274.32,
      "quantity": 1,
      "sku": "PANELAS-9PC",
      "image": "https://cdn.exemplo.com/produtos/panelas-cookover.jpg"
    }
  ],
  "address": {
    "city": "São Paulo",
    "state": "SP",
    "number": "1000",
    "street": "Avenida Paulista",
    "zipcode": "01310100",
    "complement": null,
    "neighborhood": "Bela Vista"
  },
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "retargeting-carrinho",
    "content": "anuncio-display",
    "term": "panelas"
  },
  "cart": {
    "abandonedAt": "2026-01-12T23:18:30.000Z",
    "createdAt": "2026-01-12T23:10:00.000Z",
    "checkoutDurationSeconds": 510
  },
  "store": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Loja Exemplo",
    "slug": "loja-exemplo"
  },
  "timestamp": "2026-01-12T23:18:30.000Z"
}
```

Não há `method`, `paidAt` nem `pix_code`. O `id` do payload é o **checkout**, não o pedido.

## Boas práticas

<AccordionGroup>
  <Accordion title="Resposta rápida">
    Responda **2xx** dentro do `timeout` do webhook (configurável na API v1; padrão 30s). Processamento pesado faça em fila assíncrona.
  </Accordion>

  <Accordion title="Retries">
    Falhas podem ser reenviadas conforme `retryAttempts` do webhook (padrão 3). Implemente idempotência no seu lado.
  </Accordion>

  <Accordion title="Idempotência">
    Use `event` + `id` (+ `leadId` em carrinho abandonado) para não processar duas vezes.
  </Accordion>

  <Accordion title="Ordem">
    A ordem de chegada **não** é garantida. Use `timestamp` para ordenar.
  </Accordion>

  <Accordion title="Teste">
    No painel **Webhooks → Enviar teste**, ou exponha local com ngrok e cadastre a URL via [POST /api/v1/webhooks](/api/v1/webhooks).
  </Accordion>
</AccordionGroup>

## Eventos legados do painel

O dashboard pode listar outros tipos (`SUBSCRIPTION_*`, `PAYMENT_*`, etc.) com formato `{ "event", "data", "timestamp", "webhookId", "storeId" }`. Para integrações novas, use apenas os cinco eventos `corvex.*` desta página.

<Note>
  Baseado na [documentação de webhook do Readme](https://corvex.readme.io/reference/webhook) (v1.1.2).
</Note>