Webhooks: receba os eventos do sistema

Faça o SG Fênix avisar outro sistema na hora em que um pedido, nota ou baixa acontece, com assinatura de segurança e novas tentativas automáticas.

3 min de leitura · Avançado · atualizado em 06/10/2026

Em vez de perguntar ao sistema "mudou alguma coisa?" a cada minuto, você cadastra um endereço e o SG Fênix avisa quando algo acontece: um pedido criado ou aprovado, uma NF-e autorizada, uma baixa registrada. Isso é um webhook. Configure em Configurações › Integrações › Webhooks.

Tela de webhooks — Cada webhook tem URL, eventos assinados e situação

Criar um webhook

1Informe o destino

Dê um Nome e a URL que vai receber os avisos. Só endereços https públicos são aceitos (por segurança, endereços locais ou da rede interna são recusados). ::

2Escolha os eventos

Marque Todos os eventos ou apenas os que interessam, como pedido.criado, pedido.status_alterado, nota.autorizada, titulo.criado, baixa.registrada, estoque.movimento, cliente.criado, devolucao_venda.confirmada e outros. ::

3Guarde o segredo

Ao criar, aparece o segredo de assinatura (começa com whsec_). Ele é mostrado uma única vez; se perder, use Novo segredo (o antigo deixa de valer). ::

4Teste

Clique em Testar: o sistema envia um evento webhook.teste na hora e mostra o resultado em Entregas. ::

O que chega

Cada evento é um POST com JSON:

{
  "id": "UUID da entrega",
  "evento": "pedido.criado",
  "criado_em": "2026-10-05T10:15:00-03:00",
  "dados": { "id": "...", "numero": 161, "status": "rascunho", "total": 1250.0 }
}

Os cabeçalhos trazem X-SGFenix-Evento, X-SGFenix-Entrega, X-SGFenix-Timestamp e X-SGFenix-Assinatura.

Conferindo a assinatura

Para ter certeza de que o aviso veio mesmo do SG Fênix, calcule o HMAC-SHA256 de timestamp + "." + corpo com o seu segredo e compare com X-SGFenix-Assinatura (formato sha256=...). Recuse avisos com timestamp com mais de 5 minutos.

$assinatura = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpoBruto, $segredo);
$ok = hash_equals($assinatura, $cabecalhoAssinatura) && abs(time() - (int) $timestamp) <= 300;

Atenção:

Confira a assinatura sobre o corpo bruto recebido, antes de converter o JSON. Qualquer mudança de espaço ou ordem quebra a assinatura.

Se o seu sistema estiver fora do ar

Responda com qualquer status 2xx em até 10 segundos para confirmar. Se não responder, o sistema tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 6 h. Depois de 20 falhas seguidas o webhook é pausado; corrija o problema e use Reativar.

Histórico de entregas de um webhook — Em Entregas você vê o resultado, o código HTTP, as tentativas e pode reenviar

Em Entregas aparecem as últimas 30 tentativas com o código HTTP e o início da resposta do seu sistema; as que falharam têm o botão Reenviar.

Dica:

A mesma entrega pode chegar mais de uma vez (por exemplo, se a sua resposta demorou). Use o campo id para ignorar repetições.

Quer avaliar este guia ou usar o sistema? Entre ou cadastre-se.