Corvex API

Comece pela visão geral dos webhooks (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.

Autenticação do POST

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

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:

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.

{
  "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`)

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

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.

Retries

Falhas podem ser reenviadas conforme retryAttempts do webhook (padrão 3). Implemente idempotência no seu lado.

Idempotência

Use event + id (+ leadId em carrinho abandonado) para não processar duas vezes.

Ordem

A ordem de chegada não é garantida. Use timestamp para ordenar.

Teste

No painel Webhooks → Enviar teste, ou exponha local com ngrok e cadastre a URL via POST /api/v1/webhooks.

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.

Baseado na documentação de webhook do Readme (v1.1.2).

Visão geral

Fundamentos

Checkout externo

Catálogo

Pedidos e entrega

Clientes

Marketing

Webhooks

Automações

Payload dos webhooks

Autenticação do POST

Eventos (configuração → payload)

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

`status` e `method`

Campos condicionais

Carrinho abandonado

Exemplo completo (`corvex.cart.abandoned`)

Boas práticas

Eventos legados do painel

​Autenticação do POST

​Eventos (configuração → payload)

​Pedidos — exemplo completo (corvex.order.paid)

​status e method

​Campos condicionais

​Carrinho abandonado

​Exemplo completo (corvex.cart.abandoned)

​Boas práticas

​Eventos legados do painel

Autenticação do POST

Eventos (configuração → payload)

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

`status` e `method`

Campos condicionais

Carrinho abandonado

Exemplo completo (`corvex.cart.abandoned`)

Boas práticas

Eventos legados do painel