Documentação da API de Webhooks - Corvex

Visão Geral

A API de Webhooks da Corvex permite que você receba notificações em tempo real sobre eventos importantes do seu sistema de checkout, como criação de pedidos e confirmação de pagamentos.

Todos os webhooks são enviados no mesmo formato padronizado, garantindo consistência e facilidade de integração.

---

Autenticação

Todos os webhooks podem incluir uma assinatura HMAC-SHA256 no header X-Webhook-Signature para validação de integridade.

Validação da Assinatura

Copiarconst crypto = require('crypto');

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

// Exemplo de uso
const isValid = validateWebhookSignature(
  request.body,
  request.headers['x-webhook-signature'],
  'seu-secret-aqui'
);

---

Eventos Disponíveis

A Corvex suporta os seguintes eventos de webhook:

---

Estrutura do Payload

Todos os webhooks seguem a mesma estrutura de payload, garantindo consistência:

Payload Base

Copiar{
  "id": "string (UUID)",
  "event": "string",
  "amount": "number",
  "status": "string",
  "method": "string",
  "client": {
    "doc": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
  },
  "items": [
    {
      "id": "string (UUID)",
      "name": "string",
      "price": "number",
      "quantity": "number",
      "externalRef": "string",
      "orderBump": "boolean",
      "gift": "boolean"
    }
  ],
  "address": {
    "city": "string | null",
    "state": "string | null",
    "number": "string | null",
    "street": "string | null",
    "zipcode": "string | null",
    "complement": "string | null",
    "neighborhood": "string | null"
  },
  "utm": {
    "ttp": "string",
    "ttclid": "string",
    "source": "string",
    "medium": "string",
    "campaign": "string",
    "content": "string",
    "term": "string",
    "page": {
      "url": "string",
      "referrer": "string"
    }
  },
  "checkout_query_params": "object | null",
  "timestamp": "string (ISO 8601)",
  "paidAt": "string (ISO 8601) | null"
}

---

Detalhamento dos Campos

Campos Principais

Status do Pedido

Método de Pagamento

Objeto client

Array items

Objeto address (Opcional)

Objeto utm (Opcional)

Objeto checkout_query_params (Opcional)

Parâmetros extras enviados no checkout. Estrutura dinâmica baseada nos atributos do checkout.

---

Exemplos de Payloads

Exemplo 1: Pedido Criado (corvex.order.created)

Copiar{
  "id": "f7542077-5b0b-4b4a-9283-8cd16fc70b96",
  "event": "corvex.order.created",
  "amount": 274.32,
  "status": "pending",
  "method": "pix",
  "client": {
    "doc": "CPF:00000000000",
    "name": "Cliente Teste",
    "email": "cliente@example.com",
    "phone": "5511999999999"
  },
  "items": [
    {
      "id": "ca9715eb-1e57-462a-9266-b0ce884c2993",
      "name": "Nome do Produto",
      "price": 274.32,
      "quantity": 1,
      "externalRef": "05da5a8d-6347-4c7c-a784-cc3a2fdafa05",
      "orderBump": false,
      "gift": false
    }
  ],
  "address": {
    "city": "São Paulo",
    "state": "SP",
    "number": "165",
    "street": "Rua de Teste",
    "zipcode": "00000000",
    "complement": null,
    "neighborhood": "Moca"
  },
  "utm": {
    "ttp": "01KET6P10HCF9EW5SBHZ6MZY7C_.tt.0",
    "ttclid": "",
    "source": "direct",
    "medium": "web",
    "campaign": "direct",
    "content": "",
    "term": "",
    "page": {
      "url": "http://localhost:3000/pay/426785fd-8140-4d43-b845-9d9005758f82",
      "referrer": ""
    }
  },
  "checkout_query_params": {
    "product": "panelas-cookover",
    "variant": "9-pecas"
  },
  "timestamp": "2026-01-12T23:16:08.198Z"
}

Exemplo 2: Pedido Pago (corvex.order.paid)

Copiar{
  "id": "f7542077-5b0b-4b4a-9283-8cd16fc70b96",
  "event": "corvex.order.paid",
  "amount": 274.32,
  "status": "paid",
  "method": "pix",
  "client": {
    "doc": "CPF:00000000000",
    "name": "Cliente Teste",
    "email": "cliente@example.com",
    "phone": "5517991301328"
  },
  "items": [
    {
      "id": "ca9715eb-1e57-462a-9266-b0ce884c2993",
      "name": "Jogo de Panelas Cookover 9 Peças (indução e gás)",
      "price": 274.32,
      "quantity": 1,
      "externalRef": "05da5a8d-6347-4c7c-a784-cc3a2fdafa05",
      "orderBump": false,
      "gift": false
    }
  ],
  "address": {
    "city": "São José do Rio Preto",
    "state": "SP",
    "number": "165",
    "street": "Rua Alcides Cardoso Treme",
    "zipcode": "15045464",
    "complement": null,
    "neighborhood": "Residencial Ana Célia"
  },
  "utm": {
    "ttp": "01KET6P10HCF9EW5SBHZ6MZY7C_.tt.0",
    "ttclid": "",
    "source": "direct",
    "medium": "web",
    "campaign": "direct",
    "content": "",
    "term": "",
    "page": {
      "url": "http://localhost:3000/pay/426785fd-8140-4d43-b845-9d9005758f82",
      "referrer": ""
    }
  },
  "checkout_query_params": {
    "product": "panelas-cookover",
    "variant": "9-pecas"
  },
  "timestamp": "2026-01-12T23:16:08.198Z",
  "paidAt": "2026-01-12T23:20:15.543Z"
}

Exemplo 3: Pedido com Múltiplos Itens

Copiar{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "corvex.order.paid",
  "amount": 599.90,
  "status": "paid",
  "method": "card",
  "client": {
    "doc": "CPF:12345678900",
    "name": "Maria Silva",
    "email": "maria@example.com",
    "phone": "5511987654321"
  },
  "items": [
    {
      "id": "item-1-uuid",
      "name": "Produto Principal",
      "price": 499.90,
      "quantity": 1,
      "externalRef": "prod-123",
      "orderBump": false,
      "gift": false
    },
    {
      "id": "item-2-uuid",
      "name": "Order Bump - Garantia Estendida",
      "price": 100.00,
      "quantity": 1,
      "externalRef": "bump-456",
      "orderBump": true,
      "gift": false
    }
  ],
  "address": {
    "city": "São Paulo",
    "state": "SP",
    "number": "123",
    "street": "Avenida Paulista",
    "zipcode": "01310100",
    "complement": "Apto 45",
    "neighborhood": "Bela Vista"
  },
  "timestamp": "2026-01-12T10:00:00.000Z",
  "paidAt": "2026-01-12T10:05:30.000Z"
}

---

Configuração de Webhooks

Endpoint de Configuração

Para configurar um webhook, você precisa criar um registro de webhook na API da Corvex. Consulte a documentação da API REST para mais detalhes sobre como criar e gerenciar webhooks.

Eventos Configuráveis

Ao configurar um webhook, você deve especificar quais eventos deseja receber. Os eventos disponíveis são:

• ORDER_CREATED - Recebe eventos corvex.order.created
• ORDER_PAID - Recebe eventos corvex.order.paid
• ORDER_CANCELLED - Recebe eventos corvex.order.cancelled
• ORDER_REFUNDED - Recebe eventos corvex.order.refunded

Headers HTTP

Todos os webhooks são enviados com os seguintes headers:

CopiarContent-Type: application/json
User-Agent: Corvex-Webhook/1.0
X-Webhook-Signature: <hmac-sha256-signature> (se configurado)

---

Considerações Importantes

Timeout

Os webhooks têm um timeout de 10 segundos. Se sua API não responder dentro desse período, o webhook será marcado como falhado.

Retry

A Corvex não realiza retries automáticos de webhooks. Se um webhook falhar, você precisará implementar sua própria lógica de retry se necessário.

Idempotência

Todos os webhooks incluem um campo id único do pedido. Recomendamos implementar idempotência no seu sistema para evitar processamento duplicado do mesmo evento.

Ordem dos Eventos

A ordem dos eventos não é garantida. Um evento corvex.order.paid pode chegar antes de um corvex.order.created em alguns casos raros. Sempre use o campo timestamp para determinar a ordem cronológica correta.

Valores Nulos

Alguns campos opcionais podem ser null. Sempre valide a presença de campos opcionais antes de usá-los.

---

Testando Webhooks

Usando ngrok (Desenvolvimento Local)

Copiar# 1. Instalar ngrok
npm install -g ngrok

# 2. Iniciar seu servidor local na porta 3000
npm run dev

# 3. Expor seu servidor local
ngrok http 3000

# 4. Use a URL do ngrok como URL do webhook
# Exemplo: https://abc123.ngrok.io/webhook

Exemplo de Endpoint de Recepção (Node.js/Express)

Copiarconst express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  const signature = req.headers['x-webhook-signature'];
  const secret = 'seu-secret-aqui'; // Deve vir das variáveis de ambiente

  // Validar assinatura (opcional, mas recomendado)
  if (signature) {
    const hmac = crypto.createHmac('sha256', secret);
    hmac.update(JSON.stringify(payload));
    const expectedSignature = hmac.digest('hex');
    
    if (signature !== expectedSignature) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }

  // Processar o webhook
  console.log('Evento recebido:', payload.event);
  console.log('Pedido ID:', payload.id);
  console.log('Status:', payload.status);

  // Implementar idempotência
  // Verificar se já processou este pedido/evento

  // Processar o evento
  switch (payload.event) {
    case 'corvex.order.created':
      console.log('Pedido criado:', payload.id);
      break;
    case 'corvex.order.paid':
      console.log('Pedido pago:', payload.id);
      break;
    case 'corvex.order.cancelled':
      console.log('Pedido cancelado:', payload.id);
      break;
    case 'corvex.order.refunded':
      console.log('Pedido reembolsado:', payload.id);
      break;
  }

  // Sempre retornar 200 OK rapidamente
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Servidor ouvindo na porta 3000');
});

---

Referências

Copiar
### Suporte

Para dúvidas ou problemas com webhooks, entre em contato com o suporte da Corvex.

---

## Changelog

### Versão 1.0.0 (2026-01-12)

- Implementação inicial da API de Webhooks
- Eventos: `corvex.order.created`, `corvex.order.paid`, `corvex.order.cancelled`, `corvex.order.refunded`
- Suporte a assinatura HMAC-SHA256
- Payload padronizado para todos os eventos
- Inclusão de dados completos (endereço, UTMs, checkout_query_params)

---

**Última atualização:** 2026-01-12