Skip to main content

​
O que são Webhooks?

Webhooks permitem que sua aplicação receba notificações automáticas quando eventos importantes acontecem na sua loja, como um pedido aprovado, reembolsado ou criado. Ao invés de fazer polling na API para verificar mudanças, os webhooks enviam uma requisição HTTP POST para a URL que você configurar.

​
Eventos disponíveis

EventoDescrição
ORDER_CREATEDPedido criado (checkout iniciado)
ORDER_APPROVEDPedido aprovado/pago
ORDER_REJECTEDPedido rejeitado
ORDER_ABANDONEDPedido abandonado
ORDER_REFUNDEDPedido reembolsado
ORDER_CHARGEDBACKPedido com chargeback

​
Formato do payload

Todos os webhooks seguem um formato padronizado: 
{
  "id": "abc123xyz",
  "event": "ORDER_APPROVED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    // Conteúdo do evento (ex: dados do pedido)
  }
}
CampoTipoDescrição
idstringIdentificador único do evento
eventstringTipo do evento
datestringData/hora do evento (ISO 8601)
dataobjectPayload do evento
Para eventos de pedido, o campo data contém os mesmos dados retornados pela API de detalhes do pedido, incluindo pacotes, variáveis, entregas e outros detalhes.

​
Segurança (HMAC-SHA256)

Cada webhook possui um secret único gerado na criação. Todas as requisições são assinadas com HMAC-SHA256 para garantir autenticidade.

​
Headers de segurança

HeaderDescrição
x-centralcart-signatureAssinatura HMAC-SHA256 em hexadecimal
x-centralcart-timestampTimestamp Unix do momento do envio

​
Verificando a assinatura

Para verificar a autenticidade do webhook, recalcule a assinatura usando o secret do webhook: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex');

  return signature === expected;
}

// No seu endpoint:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-centralcart-signature'];
  const timestamp = req.headers['x-centralcart-timestamp'];

  if (!verifyWebhook(req.body, signature, timestamp, 'seu_secret')) {
    return res.status(401).send('Assinatura inválida');
  }

  // Processar o evento
  const { event, data } = req.body;
  console.log(`Evento: ${event}`, data);

  res.status(200).send('OK');
});

​
Configuração

Webhooks podem ser configurados em Configurações > Webhooks no painel da CentralCart, ou via API.

​
Boas práticas

Responda rápido

Retorne um status 2xx o mais rápido possível. Processe o evento de forma assíncrona se necessário.

Idempotência

Use o campo id do payload para evitar processar o mesmo evento duas vezes.

Verifique a assinatura

Sempre valide o header x-centralcart-signature antes de processar o evento.

Timeout

Requisições têm timeout de 10 segundos. Se seu servidor não responder a tempo, o envio será considerado como falha.