Webhooks

Receba notificações automáticas da Nucleo Pay sempre que algo importante acontecer — como um pagamento PIX aprovado.

Pense nos webhooks como mensagens enviadas pela Nucleo Pay para o seu sistema, sem que você precise ficar consultando a API o tempo todo.

---

Por que usar webhooks?

Sem webhooks, sua aplicação teria que perguntar para a API a cada poucos segundos: "Esse pagamento já foi confirmado?" Isso é lento e ineficiente.

Com webhooks, a Nucleo Pay avisa você imediatamente quando o pagamento for confirmado. Assim você pode:

• Atualizar o status de um pedido
• Liberar acesso a um produto digital
• Enviar e-mails automáticos
• Registrar movimentações financeiras

---

Como funciona na prática?

1. Você cria um endpoint no seu sistema — ex.: https://meusite.com/webhooks/nucleopay
2. Você cadastra esse endpoint via painel ou POST /api/webhooks/create
3. Quando algo importante acontece, a Nucleo Pay envia um POST para sua URL com o evento

---

Segurança dos webhooks

Webhooks precisam ser seguros — qualquer pessoa poderia tentar enviar requisições falsas. Por isso validamos cada entrega com assinatura HMAC.

Assinatura HMAC (verificação do corpo)

Cada webhook enviado pela Nucleo Pay inclui o header:

X-NucleoPay-Signature: sha256={hex}

A assinatura é gerada com HMAC-SHA256 do corpo JSON bruto, usando o secret do webhook (whsec_...), retornado uma única vez ao criar o webhook.

Seu backend deve recalcular a assinatura e comparar. Se for igual, o evento é legítimo.

Exemplo de validação (Node.js)

import crypto from "node:crypto";

export function verifyNucleoSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const received = String(signatureHeader || "").replace(/^sha256=/, "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

---

Criando um webhook

1. Acesse API e Webhooks no painel

   Ou use POST /api/webhooks/create com Bearer token.

2. Informe a URL HTTPS

   Endpoint que receberá os eventos POST.

3. Escolha os eventos

   Use ["*"] para todos ou liste eventos específicos.

4. Guarde o secret

   O secret é exibido apenas na criação. Use-o para validar assinaturas.

POST /api/webhooks/create
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "url": "https://meusite.com/webhooks/nucleopay",
  "events": ["charge.approved", "charge.created"]
}

---

Eventos suportados

Formato do payload

{
  "event": "charge.approved",
  "timestamp": "2026-07-07T20:00:00.000Z",
  "data": {
    "chargeId": "ch_abc123",
    "order_id": "pedido-42",
    "status": "Aprovado",
    "value": 49.9,
    "title": "Meu produto",
    "external_id": "pedido-42",
    "customer_name": "João",
    "customer_email": "joao@email.com",
    "provider": "onlyup",
    "createdAt": "2026-07-07T19:55:00.000Z",
    "approvedAt": "2026-07-07T20:00:00.000Z"
  }
}

---

Boas práticas