# O que é webhook e como funciona, com exemplo

URL: https://www.cakto.com.br/blog/o-que-e-webhook

O que é webhook e como funciona

Os eventos que a Cakto envia a cada venda e como validar a assinatura de cada entrega.

### Neste artigo

- Como funciona um webhook?

- Qual a diferença entre webhook e API?

- Para que serve o webhook na venda online?

- Quais eventos de webhook a Cakto envia?

- Como configurar um webhook na Cakto?

- Como validar a origem do webhook?

- O que acontece se o webhook falhar?

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](https://www.cakto.com.br/), envia 18 eventos por webhook, da venda aprovada à assinatura cancelada ([documentação da Cakto](https://docs.cakto.com.br/conceitos/webhooks), 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:

| Item | API | Webhook |
| --- | --- | --- |
| Quem começa | O seu sistema | O sistema onde o evento acontece |
| Quando roda | Quando você consulta | Assim que o evento acontece |
| Exemplo | Criar uma cobrança ou consultar pedidos | Saber que a venda foi aprovada |

Os dois trabalham juntos. Na Cakto, a [API](https://www.cakto.com.br/api) cria o webhook e lista o histórico de eventos ([referência da API](https://docs.cakto.com.br/api-reference/webhooks/event-history)), 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](https://www.cakto.com.br/blog/comparativos/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](https://docs.cakto.com.br/conceitos/webhooks) agrupa os eventos por tipo. Alguns deles:

| Grupo | Evento | Quando dispara |
| --- | --- | --- |
| Compra | purchase_approved | Pagamento aprovado |
| Compra | purchase_refused | Pagamento recusado |
| Compra | checkout_abandonment | Checkout abandonado sem pagamento |
| Compra | refund e chargeback | Reembolso ou chargeback registrado |
| Cobrança gerada | pix_gerado | Pix gerado, aguardando pagamento |
| Assinatura | subscription_renewed | Assinatura renovada |
| Assinatura | subscription_canceled | Assinatura cancelada |

Os eventos de assinatura acompanham cada ciclo de um [pagamento recorrente](https://www.cakto.com.br/blog/o-que-e-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": "john.doe@example.com" }
  }
}
```

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](https://www.cakto.com.br/taxas).

## 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](https://docs.cakto.com.br/comece-aqui/receber-primeira-venda), consulta em 17/10/2026).

A visão geral das ferramentas de integração está na [página para desenvolvedores da Cakto](https://www.cakto.com.br/developers).

## 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](https://docs.cakto.com.br/conceitos/webhooks), 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](https://docs.cakto.com.br/conceitos/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](https://docs.cakto.com.br/conceitos/webhooks), consulta em 17/10/2026):

| Tentativa | Intervalo após a anterior |
| --- | --- |
| 1ª retentativa | 5 segundos |
| 2ª retentativa | 1 minuto |
| 3ª retentativa | 2 minutos e 30 segundos |
| 4ª retentativa | 6 minutos |
| 5ª retentativa | 30 minutos |

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](https://docs.cakto.com.br/api-reference/webhooks/resend-event), 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](https://docs.cakto.com.br/conceitos/webhooks), [receber sua primeira venda](https://docs.cakto.com.br/comece-aqui/receber-primeira-venda), [histórico de eventos do webhook](https://docs.cakto.com.br/api-reference/webhooks/event-history) e [reenviar evento do webhook](https://docs.cakto.com.br/api-reference/webhooks/resend-event). Consulta em 17/10/2026.

## Resumo

- Webhook é um aviso por HTTP enviado quando um evento acontece.

- A Cakto envia 18 eventos, da venda aprovada à assinatura cancelada.

- Valide a assinatura HMAC e responda 2xx em até 8 segundos.

## Perguntas frequentes

### Webhook é a mesma coisa que websocket?

Não. O webhook envia uma requisição HTTP a cada evento. O websocket mantém uma conexão aberta, com mensagens nos dois sentidos.

### Como testar um webhook antes de uma venda?

Na Cakto, envie um evento de teste para a sua URL. O conteúdo é um exemplo fixo e não retrata a sua conta (documentação da Cakto, consulta em 17/10/2026).

### Preciso saber programar para usar webhook?

Não necessariamente. Ferramentas de automação sem código recebem webhooks e repassam os dados para outros aplicativos.

### O que é o Webhook V2 da Cakto?

Versão criada só pelo painel. Ela entrega juntos os pedidos da mesma cobrança, como o principal e o order bump (documentação da Cakto, consulta em 17/10/2026).

Crie a conta e cadastre o primeiro webhook da sua operação.

## Leia também

### O que é gateway de pagamento e como funciona

O caminho de uma compra do checkout até o banco e o que muda entre gateway, checkout, adquirente, subadquirente e intermediador.

### O que é MCP (Model Context Protocol)?

O protocolo que deixa uma IA usar ferramentas: abrir arquivo, consultar banco, criar checkout. Como conectar.

### O que é upsell, cross-sell e downsell

Como montar o funil de upsell e downsell na Cakto, com o upsell aceito em 1 clique.
