Guia prático

Kiwify webhook timeout: por que acontece e como resolver

Você fez a venda, o dinheiro entrou, mas o cliente não recebeu o acesso. A pista costuma ser a mesma: o webhook da Kiwify deu timeout ao avisar o seu sistema.

Leitura de 5 minutos · Por HookSafe

Se isso já aconteceu com você, este guia mostra por que acontece, como confirmar nos logs da Kiwify e como resolver, com e sem escrever código.

O que é um "webhook timeout" na Kiwify

Quando acontece uma venda, a Kiwify dispara um webhook: envia um POST para a URL que você configurou, avisando "pedido aprovado". O seu servidor precisa responder rápido, com um código HTTP 2xx (200, 201, etc.), confirmando que recebeu.

O timeout acontece quando o seu servidor demora demais para responder, ou não responde. A Kiwify espera a confirmação por um tempo limitado. Se ela não vem, a tentativa é considerada falha, e o evento que deveria liberar o produto do cliente não é processado. A venda "some" no seu sistema mesmo tendo sido paga.

Por que o timeout acontece

Quase sempre a causa é uma destas três:

• O servidor está lento ou fora do ar naquele instante. Um pico de vendas, um deploy, uma instabilidade da hospedagem, e ele não responde a tempo.
• Você processa tudo de forma síncrona. Se, ao receber o webhook, o seu código já sai gerando acesso, enviando e-mail e chamando outras APIs antes de responder à Kiwify, tudo isso conta no tempo. Estourou o limite, virou timeout.
• O endpoint é pesado. Consultas lentas ao banco ou chamadas externas demoradas antes de responder aumentam o risco.

Como confirmar nos logs da Kiwify

A Kiwify guarda o histórico de cada webhook. Para investigar:

1. Entre na sua conta e vá em Apps e depois Webhooks.
2. No webhook do seu produto, clique nos três pontinhos e em Ver logs.
3. Você verá cada evento, o status e a resposta. Ali dá pra identificar quais falharam.

Se aparecerem eventos falhos ou sem resposta 2xx, o timeout está confirmado.

Como resolver (a solução de raiz)

A regra de ouro é uma só: responda 2xx primeiro, processe depois.

Ao receber o webhook, o seu servidor deve apenas guardar o evento (numa fila ou no banco) e responder 2xx na hora. O trabalho pesado (liberar acesso, e-mail, integrações) roda em segundo plano, depois da resposta. Assim, mesmo que o processamento demore, a Kiwify recebe a confirmação rápido e não dá timeout.

Além disso:

• Deixe o endpoint leve. Nada de consulta lenta ou chamada externa antes de responder. Só o mínimo para registrar o evento.
• Trate as duplicatas. A Kiwify reenvia automaticamente webhooks que falharam, e isso pode gerar entregas repetidas. Para não liberar o mesmo produto duas vezes, deduplique usando um identificador do recurso que vem dentro dos dados (o id do pedido/venda).
• Aguente picos. Se o timeout só acontece em dia de lançamento, o problema é capacidade. O processamento assíncrono acima já ajuda muito, porque tira o peso da resposta.

E os webhooks que já falharam?

Os que falharam antes da correção você recupera na mão: na mesma tela de Ver logs, clique nos três pontinhos ao lado do evento e em Reenviar (ou selecione vários e use Reenviar webhooks). Isso reprocessa a venda que tinha ficado para trás.

Se o seu servidor ficou muito tempo fora do ar, reenviar um por um vira um trabalho chato, e há um limite de até quando a Kiwify mantém e retenta esses eventos.

Como evitar que isso volte a acontecer

Depois de aplicar o processamento assíncrono, o risco cai bastante. Mas dois cenários continuam existindo: o seu servidor cair no meio de um lançamento, e a necessidade de reenviar em massa quando isso acontece.

É exatamente para isso que existe o HookSafe. Em vez de a Kiwify enviar o webhook direto pro seu servidor, ela envia pro HookSafe, que responde 2xx na hora (então nunca dá timeout do lado da plataforma), guarda o evento e reentrega pro seu sistema. Se o seu servidor estiver fora do ar, o HookSafe insiste (1min, 5min, 15min, 1h), e você ainda tem um botão de replay para reenviar tudo que falhou de uma vez. Você aponta a URL uma vez e não precisa reescrever seu sistema.

Se você prefere resolver por conta própria, os passos acima já cobrem a maior parte dos casos. O HookSafe é para quem não quer construir e manter essa camada de confiabilidade sozinho.

Resumo

O timeout do webhook da Kiwify acontece quando o seu servidor demora ou falha ao responder. A correção de raiz é responder 2xx na hora e processar o resto em segundo plano, mantendo o endpoint leve e tratando duplicatas pelo id do pedido. Os eventos que já falharam você reenvia pelos logs da Kiwify. E, para não depender de tudo dar certo sempre, uma camada como o HookSafe garante a entrega e o replay.