O que é webhook e como funciona

Webhook é um aviso automático que um sistema envia a outro, numa requisição HTTP, assim que um evento acontece. Exemplo: numa venda de R$ 197 aprovada, a plataforma de pagamento envia os dados da compra ao sistema da loja, que libera o acesso.

A Cakto, plataforma brasileira de pagamentos para produtores digitais, envia 18 eventos por webhook, da venda aprovada à assinatura cancelada (documentação da Cakto, consulta em 17/10/2026).

Como funciona um webhook?

Um webhook funciona em quatro passos:

• Você cadastra uma URL e escolhe os eventos que quer receber
• O evento acontece, como um Pix pago ou uma assinatura renovada
• O sistema envia um POST com os dados do evento para a sua URL
• A sua aplicação responde com status 2xx para confirmar o recebimento

Qual a diferença entre webhook e API?

A diferença está em quem começa a troca de dados:

Os dois trabalham juntos. Na Cakto, a API cria o webhook e lista o histórico de eventos (referência da API), e o webhook avisa cada evento de venda.

Para ver a API e os webhooks da Cakto ao lado dos de outra plataforma, veja o comparativo Cakto vs Hotmart.

Para que serve o webhook na venda online?

Na venda de produto digital, o webhook leva cada mudança na venda para outros sistemas, sem ação manual. Exemplos:

• Liberar o acesso no seu sistema quando a compra é aprovada
• Mandar uma mensagem a quem abandonou o checkout
• Avisar o time quando uma assinatura atrasa ou é cancelada
• Registrar reembolsos e chargebacks no controle financeiro

Quais eventos de webhook a Cakto envia?

A documentação da Cakto agrupa os eventos por tipo. Alguns deles:

Os eventos de assinatura acompanham cada ciclo de um pagamento recorrente.

Fora o abandono de checkout, todos os eventos chegam no mesmo formato de pedido. O abandono não traz id nem valor, porque não houve pedido.

Exemplo abreviado de uma venda aprovada, no formato da documentação:

{
  "secret": "SEU_SECRET",
  "event": "purchase_approved",
  "data": {
    "id": "b3df956e-1998-4322-b091-ac0c54f7b4ba",
    "status": "paid",
    "offer_type": "main",
    "amount": 197.0,
    "paymentMethod": "credit_card",
    "customer": { "name": "John Doe", "email": "[email protected]" }
  }
}

O campo event diz o que aconteceu, e data traz o pedido.

Num pedido com order bump ou upsell, cada produto chega como um pedido próprio. O campo offer_type diz o tipo de oferta, e parent_order aponta o pedido de origem.

O data também traz o campo fees, com o total de taxas da venda. Os valores de cada meio de pagamento estão nas taxas da Cakto.

Como configurar um webhook na Cakto?

• Crie o webhook no painel da Cakto ou pela rota Criar Webhook da API
• Informe a URL de destino, os produtos e os eventos que ele vai receber
• Guarde o secret que a Cakto gera para esse webhook
• Envie um evento de teste e confira a resposta da sua aplicação

Pela API, a chave precisa do escopo write webhooks, e o webhook só recebe eventos dos produtos informados (guia da primeira venda, consulta em 17/10/2026).

A visão geral das ferramentas de integração está na página para desenvolvedores da Cakto.

Como validar a origem do webhook?

Cada entrega da Cakto leva os cabeçalhos X-Cakto-Timestamp e X-Cakto-Signature. A assinatura é um HMAC-SHA256 do texto {timestamp}.{corpo}, com o seu secret como chave.

Calcule o HMAC sobre o corpo cru, antes de converter o JSON, e compare com a assinatura recebida.

O exemplo da documentação recusa entregas com mais de 5 minutos (guia de webhooks da Cakto, consulta em 17/10/2026):

import hashlib
import hmac
import time


def veio_da_cakto(corpo: bytes, timestamp: str, assinatura: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    esperado = hmac.new(secret.encode(), f"{timestamp}.".encode() + corpo, hashlib.sha256)
    return hmac.compare_digest(assinatura, f"v1={esperado.hexdigest()}")

Outra forma é comparar o campo secret do corpo com o valor guardado. A Cakto recomenda a assinatura, e a URL do webhook precisa usar HTTPS (guia de webhooks).

O que acontece se o webhook falhar?

Se a rede falhar ou a resposta passar de 8 segundos, a Cakto faz até 5 retentativas (documentação da Cakto, consulta em 17/10/2026):

Uma resposta de erro da sua aplicação, como 500, não é reenviada automaticamente. Corrija o problema e reenvie a entrega com a rota Reenviar Evento, a partir do histórico de eventos.

Como o tempo limite é curto, responda 2xx assim que receber e deixe o processamento pesado para depois, numa fila.

As retentativas podem entregar o mesmo evento mais de uma vez. Use o data.id do pedido como chave e ignore o que já foi processado.

Fontes: documentação da Cakto, guia de webhooks, receber sua primeira venda, histórico de eventos do webhook e reenviar evento do webhook. Consulta em 17/10/2026.

Perguntas frequentes