Webhooks

Um webhook avisa o seu sistema quando algo muda na sua conta: uma cobrança foi paga, um reembolso saiu, um saque foi concluído. Você cadastra uma URL com uma inscrição de webhook, escolhe os eventos e a Gates2b faz um POST assinado nessa URL a cada evento. Assim você não precisa consultar a API em loop.

Como receber eventosCopiar link da seção

curl -X POST "https://api.gates2b.com/webhook-subscriptions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://loja.example.com/webhooks/pagamentos",
    "subscribedEvents": ["charge.paid", "charge.refunded", "payout.paid", "payout.failed"]
  }'

Cada inscrição tem uma URL. Para mandar eventos diferentes para URLs diferentes, crie uma inscrição por URL. Um evento assinado por mais de uma inscrição é entregue a cada uma delas, com assinatura e id próprios.

Para gerenciar as inscrições: Listar, Consultar, Atualizar, Rotacionar segredo, Pausar, Ativar e Revogar.

Status da inscriçãoCopiar link da seção

A inscrição nasce active e só recebe eventos nesse status. Você pausa para manutenção do endpoint e revoga para desligar a URL. A Gates2b também pausa a inscrição sozinha quando, na hora da entrega, a URL aponta para um endereço não permitido.

O que acontece com os eventos em cada mudança:

• Pausar: eventos gerados durante a pausa não são criados para a inscrição, e uma nova tentativa que vencer nesse intervalo é descartada. Ao ativar, a entrega recomeça só com eventos novos.
• Revogar: as tentativas pendentes são descartadas. Para usar outra URL, crie uma inscrição nova.
• Pausa automática: corrija a callbackUrl com Atualizar antes de Ativar; senão a próxima entrega pausa a inscrição de novo.

EventosCopiar link da seção

Use em subscribedEvents o nome exato da primeira coluna. A API aceita um nome com erro de grafia, mas nenhum evento com esse nome existe, e a inscrição não recebe nada.

Sobre os saques:

• A sequência normal é payout.completed e depois payout.paid ou payout.failed. Alguns meios de saque pulam o payout.completed e enviam só o desfecho; um saque recusado na criação recebe só payout.failed.
• O desfecho pode mudar: um saque dado como falho pode ser confirmado depois, e um saque pago pode ser revertido. Os dois eventos chegam. Vale o que tiver o payout.updatedAt mais recente.
• Saques automáticos (settlementConfig na cobrança) não enviam payout.*; eles têm os eventos auto_payout.*.

Pagamentos em criptoCopiar link da seção

Há um evento por status do pagamento. O x-Webhook-Correlation-Id é o id do pagamento em cripto.

Libere o pedido só em crypto_payment.finished. crypto_payment.confirmed não é pagamento concluído.

Formato da entregaCopiar link da seção

A Gates2b faz um POST na callbackUrl com Content-Type: application/json. O corpo é o objeto do evento; os headers abaixo vêm em toda entrega.

Nomes de header não diferenciam maiúsculas de minúsculas. A maioria dos frameworks os entrega em minúsculas (x-webhook-signature).

Use o header x-Webhook-Event-Type para decidir como tratar a entrega. O corpo muda de evento para evento, e nem todo corpo traz o nome do evento.

{
  "event": "charge.paid",
  "charge": {
    "id": "019ecb7a-2ab0-7744-982f-e9d951d61746",
    "status": "PAID",
    "grossAmount": "100.00",
    "currency": "BRL",
    "externalReference": "pedido-123",
    "description": "Assinatura mensal",
    "customer": {
      "name": "Maria Silva",
      "email": "cliente@example.com",
      "document": "12345678909",
      "phone": "11999998888",
      "country": null
    },
    "paymentMethod": {
      "type": "PIX",
      "brand": null,
      "authorizationCode": null,
      "expMonth": null,
      "expYear": null,
      "funding": null,
      "last4": null,
      "bankIspb": "00000000"
    },
    "paidAt": "2026-06-15T14:10:05.094Z",
    "createdAt": "2026-06-15T14:00:00.000Z"
  },
  "attempt": {
    "id": "019ecb7b-0c41-7a5e-8d0f-3c2a9e1b7f42",
    "paymentMethod": "PIX",
    "idempotencyKey": "pedido-123-tentativa-1",
    "payer": {
      "name": "Maria Silva",
      "email": null,
      "document": "12345678909",
      "phone": null,
      "country": null
    }
  }
}

Os eventos invoice.* trazem o mesmo objeto da notificação legada.

O corpo de cada evento, campo a campo, está em Eventos de webhook.

Verificar a assinaturaCopiar link da seção

Toda entrega é assinada com HMAC-SHA256 usando o secret da inscrição. Verifique antes de confiar no corpo:

1. Leia t e v1 do header x-Webhook-Signature (t=1718460605,v1=5f2b…).
2. Rejeite a entrega se t estiver a mais de 300 segundos (5 minutos) do relógio do seu servidor, para cima ou para baixo. Isso barra o reenvio de uma entrega capturada.
3. Calcule HMAC-SHA256(secret, t + "." + corpo) em hexadecimal minúsculo. corpo são os bytes exatos recebidos, antes de qualquer parse de JSON.
4. Compare o resultado com v1 em tempo constante.

Reserializar o JSON muda espaços e ordem das chaves e quebra a assinatura. Configure o framework para entregar o corpo cru nessa rota. Mantenha o relógio do servidor sincronizado (NTP), ou a janela de 5 minutos rejeita entregas válidas.

import crypto from 'node:crypto';
import express from 'express';

const TOLERANCE_SECONDS = 300;

function verifySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((part) => {
      const [key, ...value] = part.trim().split('=');
      return [key, value.join('=')];
    }),
  );
  const timestamp = Number.parseInt(parts.t, 10);
  if (!Number.isFinite(timestamp) || !parts.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.`)
    .update(rawBody) // Buffer com o corpo cru
    .digest();
  const received = Buffer.from(parts.v1, 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

const app = express();

// express.raw: req.body chega como Buffer, sem parse
app.post('/webhooks/pagamentos', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('x-webhook-signature') ?? '';
  if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const eventId = req.get('x-webhook-event-id');
  const eventType = req.get('x-webhook-event-type');
  const payload = JSON.parse(req.body.toString('utf8'));

  // Grave eventId como processado e trate o evento fora da requisição.
  res.sendStatus(200);
});

Guardar o segredoCopiar link da seção

Se perder o segredo ou suspeitar de vazamento, rotacione. O anterior deixa de valer na hora, inclusive para novas tentativas de eventos já gerados. A página de Rotacionar segredo mostra como trocar sem rejeitar entregas.

Novas tentativasCopiar link da seção

A entrega conta como recebida quando a sua URL responde 2xx em até 10 segundos. Qualquer outro caso é falha: status 3xx (redirecionamentos não são seguidos), 4xx, 5xx, tempo esgotado ou erro de conexão. Depois de uma falha, a Gates2b tenta de novo com intervalo crescente:

Cada espera varia até 25% para mais ou para menos. Depois da 15ª tentativa (cerca de 32 horas após o evento), ou 7 dias após o evento, o que vier primeiro, a entrega é abandonada e não há nova tentativa automática. Nesse caso, consulte o estado do recurso pela API.

• failureCount da inscrição soma cada tentativa que falha e volta a 0 na primeira entrega aceita.
• Pausar ou revogar a inscrição descarta as tentativas pendentes. Eventos gerados enquanto ela não está active não são entregues depois.
• Se, no momento da entrega, a URL apontar para um endereço não permitido (IP privado, porta fora de 80, 443, 8080 e 8443), a entrega é abandonada e a inscrição passa para paused.

Responda 2xx assim que validar a assinatura e processe o evento depois. Um processamento lento que estoura os 10 segundos vira falha e gera nova tentativa.

IdempotênciaCopiar link da seção

A entrega é pelo menos uma vez: o mesmo evento pode chegar mais de uma vez, e a ordem de chegada não é garantida.

• Guarde o x-Webhook-Event-Id de cada entrega processada e ignore as que repetirem o id. Novas tentativas da mesma entrega usam o mesmo id.
• Torne a ação do seu lado idempotente também pelo recurso (id da cobrança, do saque…). Um reenvio manual gera uma entrega nova, com outro x-Webhook-Event-Id.
• Não confie só no valor do webhook para liberar um pedido. Compare com o pedido do seu lado ou consulte a cobrança pela API.

Para pedir de novo a notificação de uma invoice paga, use Reenviar webhook. O reenvio chega às inscrições que assinam invoice.paid.

Webhook legado configurado no painelCopiar link da seção

Contas antigas podem ter uma URL de notificação cadastrada no painel, em Integração. Essa URL recebe um POST quando o status de uma invoice muda, criada pelos endpoints legados de /invoices.

Ela continua funcionando, mas tem limites que a inscrição de webhook não tem:

• Sem assinatura. Não há x-Webhook-Signature; você não consegue provar que a chamada veio da Gates2b.
• Sem a política de novas tentativas. Se o seu servidor falhar, a notificação pode se perder. Confira o status pela API ou use Reenviar webhook.
• Sem escolha de eventos. Toda mudança de status chega na mesma URL.

Para integração nova, use inscrição de webhook com invoice.paid e invoice.refunded. Se você já usa a URL do painel, mantenha as duas até migrar o seu endpoint para a verificação de assinatura; depois apague a URL do painel para não processar o mesmo pagamento duas vezes.

Exemplo de corpo, com a invoice paga:

{
  "id": 72276,
  "id_transaction": "26182891-7569-414f-aa60-4f2b8e1c9d3a",
  "transaction_pix_id": "e3c1a2b4-50d3-4de7-911d-8a7b6c5d4e3f",
  "external_reference": "pedido-123",
  "emv": "00020101021226...6304ABCD",
  "amount": 120,
  "status": "Pagamento realizado",
  "international_status": "PAYMENT_RECEIVED",
  "name_client": "MARIA SILVA",
  "document_client": "12345678909",
  "createdAt": "2026-06-15T12:24:49.056Z",
  "user": {}
}

international_status é o campo estável para o seu código. Valores: WAITING_PAYMENT, WAITING_PROCESSING, REVIEW_REQUIRED, PAYMENT_RECEIVED, PARTIALLY_PAID, PAYMENT_EXPIRED, PAYMENT_FAILED, WITHDRAWAL_IN_PROGRESS, WITHDRAWAL_IN_PROCESSING, WITHDRAWAL_COMPLETED, WITHDRAWAL_FAILED, REFUND_REQUESTED e BALANCE_REMOVED. O pagamento confirmado é PAYMENT_RECEIVED. status é o mesmo estado em texto, em português, e pode mudar.