Webhooks

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

Evento	Descrição
`ORDER_CREATED`	Pedido criado (checkout iniciado)
`ORDER_UPDATED`	Detalhes do pedido foram atualizados (cliente, status, campos de checkout, escolhas do produto, etc.)
`ORDER_APPROVED`	Pedido aprovado/pago
`ORDER_REJECTED`	Pedido rejeitado
`ORDER_ABANDONED`	Pedido abandonado
`ORDER_REFUNDED`	Pedido reembolsado
`ORDER_CHARGEDBACK`	Pedido com chargeback
`PACKAGE_CREATED`	Produto criado
`PACKAGE_UPDATED`	Produto alterado
`PACKAGE_DELETED`	Produto deletado
`LICENSE_KEY_UPDATED`	License keys de um produto foram adicionadas ou removidas
`FEEDBACK_CREATED`	Nova avaliação recebida em um pedido

O evento ORDER_UPDATED é disparado sempre que um administrador edita o pedido pelo painel. Caso a atualização também resulte em uma mudança de status para APPROVED ou REFUNDED, os eventos correspondentes (ORDER_APPROVED / ORDER_REFUNDED) também são disparados. Assine apenas os que fizerem sentido para o seu fluxo.

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

Campo	Tipo	Descrição
`id`	`string`	Identificador único do evento
`event`	`string`	Tipo do evento
`date`	`string`	Data/hora do evento (ISO 8601)
`data`	`object`	Payload do evento

O conteúdo de data varia conforme o grupo do evento. Veja abaixo o formato de cada um:

Eventos de pedido (ORDER_*)

Todos os eventos ORDER_* (ORDER_CREATED, ORDER_UPDATED, ORDER_APPROVED, ORDER_REJECTED, ORDER_ABANDONED, ORDER_REFUNDED, ORDER_CHARGEDBACK) compartilham o mesmo formato: o campo data contém os mesmos dados retornados pela API de detalhes do pedido, incluindo pacotes, variáveis, entregas e outros detalhes.

{
  "id": "abc123xyz",
  "event": "ORDER_APPROVED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    // Dados do pedido (mesmo objeto da API de detalhes do pedido)
  }
}

PACKAGE_CREATED e PACKAGE_DELETED

Trazem o produto no campo data.package:

{
  "id": "abc123xyz",
  "event": "PACKAGE_CREATED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    "package": {
      // Dados do produto
    }
  }
}

PACKAGE_UPDATED

Traz o estado do produto antes e depois da edição, para que você compare o que mudou:

{
  "id": "abc123xyz",
  "event": "PACKAGE_UPDATED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    "before": {
      // Estado do produto antes da edição
    },
    "after": {
      // Estado do produto após a edição
    }
  }
}

LICENSE_KEY_UPDATED

Traz o produto afetado em data.package e as chaves que foram adicionadas e removidas naquela edição:

{
  "id": "abc123xyz",
  "event": "LICENSE_KEY_UPDATED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    "package": {
      // Dados do produto
    },
    "added_keys": ["CHAVE-NOVA-1", "CHAVE-NOVA-2"],
    "removed_keys": ["CHAVE-ANTIGA-1"]
  }
}

FEEDBACK_CREATED

Disparado quando o cliente envia uma avaliação do pedido. Traz a avaliação em data.feedback, junto com a identificação do pedido avaliado:

{
  "id": "abc123xyz",
  "event": "FEEDBACK_CREATED",
  "date": "2026-02-20T15:30:00.000Z",
  "data": {
    "feedback": {
      "id": 1,
      "rating": 5,
      "message": "Entrega rápida, recomendo!",
      "is_public": true,
      "created_at": "2026-02-20T15:30:00.000-03:00",
      "order": {
        "internal_id": "1b2fe2a9697a0ac07ebd933309b4f9a8d1120c06",
        "client_name": "João da Silva",
        "client_email": "[email protected]",
        "client_discord": null
      }
    }
  }
}

is_public reflete a configuração de publicação automática da loja no momento do envio. Avaliações que entram como privadas só aparecem na loja depois de publicadas, pelo painel ou pelo endpoint PATCH /app/feedback/{feedback-id}.

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

Header	Descrição
`x-centralcart-signature`	Assinatura HMAC-SHA256 em hexadecimal
`x-centralcart-timestamp`	Timestamp 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.

Documentação da API

Endpoints de aplicação

Storefront API (Public)

O que são Webhooks?

Eventos disponíveis

Formato do payload

Segurança (HMAC-SHA256)

Headers de segurança

Verificando a assinatura

Configuração

Boas práticas

Responda rápido

Idempotência

Verifique a assinatura

Timeout

​O que são Webhooks?

​Eventos disponíveis

​Formato do payload

​Segurança (HMAC-SHA256)

​Headers de segurança

​Verificando a assinatura

​Configuração

​Boas práticas

Responda rápido

Idempotência

Verifique a assinatura

Timeout

O que são Webhooks?

Eventos disponíveis

Formato do payload

Segurança (HMAC-SHA256)

Headers de segurança

Verificando a assinatura

Configuração

Boas práticas