Webhooks

Após uma alteração de estado de pagamento ou saque, a Cobrex envia um pedido HTTP para o URL configurado no comerciante ou para o callback indicado na criação da operação.

Corpo do pedido

Operação	Corpo
Pagamento	JSON do objeto de pagamento (ver modelo).
Saque	JSON do objeto de saque (ver modelo).

Confirme método e cabeçalhos com a especificação atual; use as verificações abaixo para segurança.

Resposta do seu servidor

Quando o webhook é aceite e processado (ou colocado numa fila interna com garantia de processamento), o endpoint deve devolver HTTP 200. A Cobrex interpreta isto como entrega bem-sucedida.

Qualquer outro resultado (5xx, 4xx, timeout, queda de ligação) conta como falha — aplicam-se os reenvios abaixo.

Reenvios após falha

Se a entrega não for bem-sucedida, a Cobrex agenda nova tentativa com atraso crescente:

• O contador de tentativas aumenta enquanto for inferior a 9.
• Com 9 ou mais tentativas neste ciclo, não há mais reenvios (next_attempt_at fica vazio).
• O intervalo até à próxima tentativa depende do valor atual de attempts ao planear.

Intervalo até à próxima tentativa:

attempts ao planear	Espera até à próxima entrega
1	10 segundos
2	30 segundos
3	1 minuto
4	5 minutos
5	15 minutos
6	1 hora
7	4 horas
8	16 horas
Outros valores tratados (fallback da implementação)	15 minutos

Poderá receber até nove falhas consecutivas neste esquema antes de pararem os reenvios; confirme o comportamento em produção com o suporte Cobrex se a política mudar.

Verificação 1 — endereço IP

Aceite apenas IPs de confiança. À data desta documentação:

46.166.162.83

As listas podem mudar — confirme a lista de produção com o suporte.

Verificação 2 — cabeçalho x-signature

1. Guarde o corpo em bruto como string/buffer antes de JSON.parse.
2. HMAC-SHA256 com o seu segredo (o mesmo da API, ou segredo dedicado — confirme com a Cobrex).

Padrão esperado:

signature_hex = HMAC-SHA256( key = api_secret, message = JSON.stringify(data) ).toString('hex')

Na prática, verificar HMAC sobre a cadeia do corpo em bruto costuma ser mais estável:

const crypto = require('crypto');

function verifyWebhookSignature(rawBodyString, receivedHex, apiSecret) {
  const expected = crypto.createHmac('sha256', apiSecret).update(rawBodyString).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(receivedHex, 'hex'));
}

Confirme com a Cobrex qual variante a produção utiliza.

Recomendações

• Responda HTTP 200 de imediato após validar e enfileirar; execute trabalho pesado de forma assíncrona.
• Torne o handler idempotente por payment_id / payout_id.
• Registe cabeçalhos e corpos em depuração (nunca segredos).

Ver também: Autenticação e assinatura.