Webhooks

Webhooks (também conhecidos como retorno de chamada web) são um método simples que permite a uma aplicação ou sistema fornecer informações em tempo real sempre que um evento ocorre. É uma forma passiva de receber dados entre dois sistemas, por meio de uma solicitação HTTP POST.

As notificações de webhook podem ser configuradas para cada uma das integrações criadas na sua organização. Você também pode disparar um evento de teste que, antes de ir para produção, permite validar o funcionamento correto das suas notificações.

Uma vez configuradas, as notificações são enviadas sempre que ocorrer um dos eventos cadastrados. Isso evita a necessidade de verificações constantes, prevenindo a sobrecarga do sistema e a perda de dados em situações críticas.

Configurar

Webhooks são configurados no Painel, na área de integrações da sua organização. No cadastro você informa:

O secret é gerado junto e é o que permite provar que o POST veio da Pixlog. Ele pode ser rotacionado pelo Painel a qualquer momento; a rotação invalida o secret anterior no ato.

Pelo Painel você também acompanha o histórico de entregas, dispara um evento de teste e reenvia uma entrega que falhou.

O que você recebe

{
  "id": "evt_7b40c1f49a2e",
  "type": "report.created",
  "createdAt": "2026-08-27T13:04:11.000Z",
  "organizationId": "org_2e7b40c1f49a",
  "data": {
    "id": "rpt_9c1f4a2e7b40",
    "type": "PIXLOG"
  }
}

Junto com o corpo vêm os headers:

Content-Type: application/json
x-signature: ts=1756300000,v1=9f2c1ad0b4e7...e40b
x-request-id: dlv_1a7d0e5b93cc

x-signature é a assinatura do evento. x-request-id identifica a entrega. Informe esse valor ao acionar o suporte.

Eventos

No cadastro do endpoint você escolhe quais tipos assinar. O curinga * assina todos, inclusive tipos que venham a existir no futuro.

Operações em lote geram um evento por identificador: arquivar 30 relatórios de uma vez entrega 30 eventos report.archived.

Validar a assinatura

Sua URL é pública: qualquer um pode enviar um POST para ela. Valide a assinatura antes de processar e rejeite com 401 o que não conferir.

O header x-signature traz duas partes:

A assinatura cobre um template curto, montado com o id e o type do corpo e o ts do header:

id:<id do evento>;type:<tipo do evento>;ts:<ts do header>;

Para o evento do exemplo acima, o template fica id:evt_7b40c1f49a2e;type:report.created;ts:1756300000;. A assinatura esperada é o HMAC-SHA256 desse texto com o secret do endpoint, em hexadecimal.

const parts = Object.fromEntries(
  (signatureHeader || "").split(",").map((p) => p.split("=", 2)),
);

const template = `id:${body.id};type:${body.type};ts:${parts.ts};`;
const expected = crypto.createHmac("sha256", secret).update(template).digest("hex");

const isValid = expected === parts.v1;

Em produção, compare em tempo constante com crypto.timingSafeEqual no lugar de ===, e rejeite ts fora de uma janela de cerca de cinco minutos. Nunca registre o secret em log.

Resposta esperada

Redirecionamento não é seguido: 301 e 302 contam como falha. Cadastre a URL final.

Uma entrega que falha é retentada automaticamente, com espera crescente entre as tentativas, de 5 minutos na segunda tentativa até 6 horas nas seguintes. Um endpoint que acumula falhas é desativado, e volta a receber quando você corrige a causa e o reativa pelo Painel.