Receber eventos com webhooks
Onde: Integrações → Webhooks.
Use webhooks para enviar atualizações comerciais a um sistema externo. A entrega pode acontecer mais de uma vez; utilize o identificador do evento para evitar processamento duplicado.
Cadastrar um destino
- Informe a URL do sistema que receberá as notificações.
- Escolha os eventos. Você pode usar os grupos prontos Todos, Financeiro ou Pedidos.
- Salve o destino.
- Guarde o segredo de assinatura, exibido uma única vez.
- Use o evento de teste e acompanhe as entregas.
Eventos disponíveis
| Evento | Quando é usado |
|---|---|
order.created | Um pedido foi criado. |
order.paid | O pagamento foi confirmado. |
order.cancelled | Um pedido sem pagamento foi cancelado. |
order.refunded | O pedido foi reembolsado. |
order.shipped | O código de rastreio foi informado. |
order.access_granted | O comprador recebeu acesso digital. |
Verificar a assinatura
As entregas usam POST e incluem os cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
x-noma-webhook-id | Identificador estável do evento. |
x-noma-webhook-timestamp | Timestamp da assinatura, em segundos. |
x-noma-webhook-signature | Assinatura no formato v1=<hexadecimal>. |
A assinatura é um HMAC-SHA256 de timestamp + ponto + corpo original:
import { createHmac } from "node:crypto";
const signature = `v1=${createHmac("sha256", signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex")}`;
O exemplo reproduz o cálculo da assinatura. Na implementação receptora, valide a assinatura com comparação segura, confira a atualidade do timestamp e deduplique pelo ID. Preserve o corpo original: reserializar o JSON pode alterar os bytes assinados.
Operar a integração
Confira o resultado do teste no destino e acompanhe as entregas na Nôma. Se rotacionar o segredo, atualize a configuração do receptor. Não trate order.created como confirmação de pagamento; use o evento correspondente ao resultado que sua automação precisa.
Resultado esperado: destino validado, assinatura verificada e processamento idempotente dos eventos escolhidos.
Os nomes e cabeçalhos acima foram conferidos na implementação atual de webhooks do projeto. Este guia não define uma API pública para criar produtos ou cobrar pagamentos.