Webhooks

Webhook é como a KyvoPay avisa que algo mudou: cobrança paga, transferência concluída, reembolso confirmado. É a fonte da verdade do seu fluxo de pagamento.

1. Publique o endpoint

Requisitos do seu lado:

• URL https pública, sem autenticação por sessão.
• Responder 200 em poucos segundos. Processamento pesado vai para fila.
• Aguentar receber o mesmo evento mais de uma vez.

2. Cadastre no painel

Em Integrações → Webhooks, informe a URL e escolha os eventos. Você recebe um segredo de assinatura — guarde junto com a chave de API, com o mesmo cuidado. Se suspeitar de vazamento, use Rotacionar segredo no mesmo lugar: o segredo antigo deixa de valer e o novo aparece uma vez.

O cadastro de endpoints é feito pelo painel; a API pública com chave (X-API-Key) não tem rotas para gerenciar webhooks.

Eventos disponíveis

Só chegam ao seu endpoint os eventos que você marcou no cadastro.

3. Valide a assinatura

Cada entrega pode incluir:

Kyvo-Signature: t=<unix>,v1=<hmac>
Kyvo-Event: payment.paid
Kyvo-Delivery-Id: <uuid>

A assinatura é HMAC-SHA256 sobre:

<t>.<corpo_cru>

usando o segredo do webhook.

O timestamp também deve ser validado para reduzir risco de replay.

4. Trate entrega repetida

A mesma entrega pode chegar duas vezes — retentativa depois de timeout, por exemplo. Guarde o ID do evento e ignore o que já foi processado:

const jaProcessado = await db.eventos.findUnique({ where: { id: evento.id } });
if (jaProcessado) return new Response("ok", { status: 200 });

5. Retentativas

Resposta diferente de 2xx ou demora demais fazem a entrega ser repetida com intervalos crescentes. Responder 200 e falhar depois, no seu processamento, não gera nova tentativa — por isso o 200 só deve sair depois que o evento estiver seguro na sua fila ou no seu banco.

Regras de entrega:

• Timeout: cada tentativa espera até 8 segundos pela sua resposta.
• Tentativas: até 8 no total. A espera entre elas começa em cerca de 5 segundos, dobra a cada falha e nunca passa de 5 minutos.
• Redirecionamento: uma resposta 3xx conta como falha — cadastre a URL final, sem redirecionar.
• Reenvio manual: em Integrações → Webhooks, cada entrega tem o botão Reenviar, útil depois que você corrigir o problema do seu lado.
• Mesmo identificador: todas as tentativas de um evento levam o mesmo ID de evento, então o tratamento de repetição da seção anterior cobre também o reenvio manual.