Configuración

Adicionar um endereço

Cada endereço recebe só os eventos que você escolher.

1. Abra Webhooks

   Acesse Configurações, abra Avançado, escolha Webhooks e clique em Novo endereço.

2. Informe para onde avisar

   Em Para onde avisar cole o Endereço web (deve começar com https) e, se quiser, um nome ou nota. Deixe marcado Enviar avisos para este endereço.

3. Escolha o que avisar

   Em O que avisar marque os eventos que interessam ou use Selecionar todos.

4. Salve e copie a chave de assinatura

   Clique em Salvar endereço. Aparece Guarde sua chave de assinatura (começa com whsec_): copie para o seu sistema.

5. Envie um teste

   Use Enviar teste para receber um aviso test.webhook e confirmar que seu sistema responde.

Eventos disponíveis

Os eventos são agrupados por módulo. Alguns exemplos:

• Pagamentos e links de pagamento: payment.succeeded, payment.failed, payment_link.paid.
• Faturas e assinaturas: invoice.paid, subscription.canceled.
• Clientes e leads: customer.created, lead.converted.
• Conversas: conversation.assigned, conversation.message.received.
• CRM, acompanhamentos e fluxos: deal.won, follow_up.completed, flow_run.completed.

Verificar a assinatura

Cada aviso traz o cabeçalho X-Recaudo-Signature com o horário (t) e uma assinatura HMAC-SHA256 (v1) de t.corpo feita com sua chave de assinatura. Calcule você mesmo e compare antes de confiar no aviso:

X-Recaudo-Signature: t=1760000000,v1=5f2b9c...
X-Recaudo-Event-Id: 9b1d2c3e-...
X-Recaudo-Event-Type: payment.succeeded

<?php
$secret  = getenv('RECAUDO_WEBHOOK_SECRET'); // whsec_...
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_RECAUDO_SIGNATURE'] ?? '';

parse_str(str_replace(',', '&', $header), $parts); // t=...&v1=...
$expected = hash_hmac('sha256', $parts['t'] . '.' . $payload, $secret);

if (! hash_equals($expected, $parts['v1'] ?? '') || abs(time() - (int) $parts['t']) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
http_response_code(200);

const crypto = require('crypto');

// Usa el cuerpo crudo (raw body), no el JSON ya interpretado
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}

A estrutura de cada evento está na referência de webhooks da API.

Revisar envios e reenviar

Seu sistema deve responder com um código 2xx. Se não responder ou falhar, o Recaudo tenta de novo até 5 vezes, com esperas cada vez maiores.

1. Abra o detalhe

   Na lista de endereços clique em Ver detalhe.

2. Confira Envios recentes

   Cada envio aparece como Recebido, Com falha ou Pendente, com o número da tentativa, os dados enviados e a resposta do seu sistema.

3. Reenvie se precisar

   Depois de corrigir o problema no seu sistema, use Reenviar no envio que falhou.

Próximo passo