Configurar webhooks

Webhooks permitem que sua aplicação seja notificada automaticamente quando eventos ocorrem — como um pagamento confirmado ou uma transação expirada. Em vez de fazer polling, a Bob Payments avisa você.

Configurando um webhook

Acesse o Dashboard

Vá em Webhooks → Adicionar webhook no seu projeto.

Informe a URL

Insira a URL HTTPS da sua aplicação que receberá os eventos (ex: https://suaapi.com/webhooks/bob).

Copie o secret

Um secret é gerado automaticamente. Guarde-o para verificar a autenticidade das requisições.

Webhooks funcionam normalmente no sandbox. Use-os para testar o fluxo completo antes de ir a produção.

Versões do payload (v1 e v2)

O payload de webhook é versionado. A versão é fixada por canal (webhooks do dashboard) ou por sessão (checkout):

	v2 (recomendada)	v1 (legado, congelado)
Valor	`data.amountCents` em centavos — consistente com toda a API	`data.amount` em reais
Envelope	inclui `apiVersion: "v2"`	sem marcador
Assinatura	`t=<unix>,v1=<hmac>` com proteção anti-replay	HMAC-SHA256 hex simples

Canais novos criados no dashboard nascem em v2.
Canais existentes permanecem em v1 até você migrar — quando seu consumidor estiver pronto, atualize o canal com webhookApiVersion: "v2" (via dashboard ou PATCH /api/v1/notification-channels/:id).
O shape v1 é congelado: nunca muda. Toda evolução de payload acontece na v2.

Exemplo de transaction.paid na v2 (repare em apiVersion e amountCents):

{
  "event": "transaction.paid",
  "apiVersion": "v2",
  "type": "transaction",
  "title": "Transação Paga",
  "message": "Transação de R$ 150,00 confirmada",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amountCents": 15000,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "isSandbox": false,
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:35:00.000Z"
}

Eventos disponíveis

Os exemplos abaixo mostram o formato v1 (legado). Na v2, a única diferença de dados é que data.amount (reais) é substituído por data.amountCents (centavos) e o envelope ganha apiVersion: "v2" — os demais campos são idênticos.

transaction.created

Disparado quando uma cobrança PIX é criada. Inclui pixCode e expirationDate.

{
  "event": "transaction.created",
  "type": "transaction",
  "title": "Transação Criada",
  "message": "Nova transação de R$ 150,00 aguardando pagamento",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11999990000",
      "document": "12345678901",
      "documentType": "CPF",
      "address": {
        "street": "Rua das Flores",
        "streetNumber": "123",
        "neighborhood": "Centro",
        "complement": "",
        "zipCode": "01310100",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "originDomain": "meusite.com.br",
    "isSandbox": false,
    "pixCode": "00020126580014br.gov.bcb.pix...",
    "expirationDate": "2026-03-10T15:30:00.000Z",
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:30:00.000Z"
}

transaction.paid

Disparado quando um pagamento PIX é confirmado. Use para liberar o produto ou serviço ao cliente. Inclui fee quando há taxa.

{
  "event": "transaction.paid",
  "type": "transaction",
  "title": "Transação Paga",
  "message": "Transação de R$ 150,00 confirmada",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11999990000",
      "document": "12345678901",
      "documentType": "CPF",
      "address": {
        "street": "Rua das Flores",
        "streetNumber": "123",
        "neighborhood": "Centro",
        "complement": "",
        "zipCode": "01310100",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "originDomain": "meusite.com.br",
    "isSandbox": false,
    "fee": { "amount": 3.50 },
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:35:00.000Z"
}

transaction.expired

Disparado quando uma transação expira sem pagamento. Use para notificar o cliente ou criar nova cobrança.

{
  "event": "transaction.expired",
  "type": "transaction",
  "title": "Transação Expirada",
  "message": "Transação de R$ 150,00 expirou",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11999990000",
      "document": "12345678901",
      "documentType": "CPF",
      "address": { "...": "..." }
    },
    "originDomain": "meusite.com.br",
    "isSandbox": true,
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-11T03:00:00.000Z"
}

transaction.refunded

Disparado quando uma transação é estornada.

{
  "event": "transaction.refunded",
  "type": "transaction",
  "title": "Transação Reembolsada",
  "message": "Transação de R$ 150,00 reembolsada",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": { "...": "igual ao paid" },
    "originDomain": "meusite.com.br",
    "isSandbox": false,
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T15:00:00.000Z"
}

transaction.cancelled

Disparado quando uma transação é cancelada manualmente.

{
  "event": "transaction.cancelled",
  "type": "transaction",
  "title": "Transação Cancelada",
  "message": "Transação de R$ 150,00 cancelada",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": { "...": "igual ao paid" },
    "originDomain": "meusite.com.br",
    "isSandbox": false,
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:40:00.000Z"
}

transaction.failed

Disparado quando uma transação falha no processamento.

{
  "event": "transaction.failed",
  "type": "transaction",
  "title": "transaction_failed",
  "message": "transaction_failed",
  "data": {
    "transactionId": "clx1abc123",
    "externalId": "pedido-001",
    "amount": 150.00,
    "product": "Plano Premium",
    "customerName": "João Silva",
    "customer": { "...": "igual ao paid" },
    "originDomain": "meusite.com.br",
    "isSandbox": false,
    "createdAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:33:00.000Z"
}

Verificando a assinatura

Cada requisição inclui dois headers de segurança:

Header	Descrição
`X-Webhook-Signature`	Assinatura HMAC-SHA256 (formato depende da versão — veja abaixo)
`X-Webhook-Timestamp`	ISO 8601 do momento do envio (informativo)

Verifique a assinatura sempre para garantir que a requisição veio da Bob Payments.

Use sempre o corpo bruto (raw body) da requisição para calcular o HMAC. Se o framework parsear o JSON e você re-serializar, a assinatura pode não conferir.

Com o SDK Node.js (recomendado)

O SDK detecta automaticamente o formato (v1 ou v2), compara em tempo constante e aplica a proteção anti-replay:

import { constructWebhookEvent } from '@bobpayments/sdk';

app.post('/webhooks/bob', express.raw({ type: 'application/json' }), (req, res) => {
  const event = constructWebhookEvent(
    req.body, // Buffer bruto
    req.headers['x-webhook-signature'],
    process.env.BOB_WEBHOOK_SECRET,
  );

  processEvent(event).catch(console.error); // assíncrono
  res.status(200).send('ok');               // 200 imediato
});

Assinatura v2 (anti-replay)

Na v2, o header tem o formato t=<unix>,v1=<hex>. O HMAC cobre timestamp + "." + corpo, então um webhook capturado não pode ser reenviado depois — rejeite eventos com t fora de uma janela de tolerância (recomendado: 5 minutos).

const crypto = require('crypto');

function verifyV2(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  const match = signatureHeader?.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
  if (!match) return false;
  const [, t, digest] = match;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(digest, 'hex'),
    Buffer.from(expected, 'hex'),
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= toleranceSeconds;
  return valid && fresh;
}

import hmac, hashlib, re, time

def verify_v2(raw_body: bytes, signature: str, secret: str, tolerance: int = 300) -> bool:
    match = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", signature or "")
    if not match:
        return False
    t, digest = match.groups()
    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(digest, expected) and abs(time.time() - int(t)) <= tolerance

Assinatura v1 (legado)

Na v1, o header é o HMAC-SHA256 hex do corpo, sem timestamp:

const crypto = require('crypto');

// use express.raw() para receber o corpo bruto (Buffer)
function verifyV1(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const sigBuffer = Buffer.from(signature ?? '', 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');
  return (
    sigBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(sigBuffer, expectedBuffer)
  );
}

import hmac
import hashlib

def verify_v1(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature or "", expected)

Retorne HTTP 200 imediatamente e processe o evento de forma assíncrona para evitar timeouts. Entregas podem se repetir em retry — processe de forma idempotente.

Próximos passos

Idempotência

Trate entregas repetidas sem liberar o pedido duas vezes.

Testar no sandbox

Dispare transaction.paid e transaction.expired sem dinheiro real.

Primeiros passos

Conceitos principais

Formas de integração

Webhooks

Usando a Bob

Fundamentos da API

Configurando um webhook

Versões do payload (v1 e v2)

Eventos disponíveis

Verificando a assinatura

Com o SDK Node.js (recomendado)

Assinatura v2 (anti-replay)

Assinatura v1 (legado)

Próximos passos

Idempotência

Testar no sandbox

​Configurando um webhook

​Versões do payload (v1 e v2)

​Eventos disponíveis

​Verificando a assinatura

​Com o SDK Node.js (recomendado)

​Assinatura v2 (anti-replay)

​Assinatura v1 (legado)

​Próximos passos

Idempotência

Testar no sandbox

Configurando um webhook

Versões do payload (v1 e v2)

Eventos disponíveis

Verificando a assinatura

Com o SDK Node.js (recomendado)

Assinatura v2 (anti-replay)

Assinatura v1 (legado)

Próximos passos