Visão Geral
Webhooks permitem que sua aplicação receba notificações automáticas quando eventos importantes acontecem, como quando um pagamento é confirmado ou um produto é criado.Configurando Webhooks
1
Acesse o Dashboard
Faça login no Dashboard da Garu
2
Navegue até Webhooks
Vá para Configurações → Webhooks
3
Adicione um endpoint
Clique em Adicionar webhook e insira a URL do seu endpoint
4
Selecione os eventos
Escolha quais eventos deseja receber
5
Copie o segredo
Salve o segredo do webhook para validar as assinaturas
Eventos Disponíveis
Eventos de Produto
Eventos de Transação
O evento legado
transaction.failed continua sendo entregue para endpoints que já o assinam, mas a partir da v0.8.0 prefira transaction.payment.failed / transaction.canceled / transaction.chargeback — eles separam falha técnica, cancelamento e chargeback.Eventos de Cobrança Agendada (Scheduled Charge)
Eventos de Customer (Trial)
Eventos de Payment Method (Cartão Salvo)
Eventos de Assinatura
Pix Automático não cria eventos novos. Assinaturas e cobranças no Pix Automático disparam exatamente os mesmos eventos de assinatura e transação que o cartão. Para diferenciar a origem, verifique
paymentMethod === 'pix_automatic' no payload — o campo paymentMethod aceita pix, boleto, card e pix_automatic.Eventos de Checkout Session
Formato do Payload
Todos os webhooks seguem este formato:Exemplo: Pagamento Confirmado
Exemplo: Produto Criado
Exemplo: Checkout Session Concluída
Exemplo: Checkout Session Expirada
Validando Assinaturas
Para garantir que o webhook veio da Garu, valide a assinatura:Validando Assinatura do Webhook
Boas Práticas
Responda rapidamente
Responda rapidamente
Retorne HTTP 200 o mais rápido possível (em até 5 segundos). Processe a lógica de negócio de forma assíncrona.
Implemente idempotência
Implemente idempotência
Webhooks podem ser enviados mais de uma vez. Use o ID do evento para evitar processamento duplicado.
Use HTTPS
Use HTTPS
Configure seu endpoint com HTTPS para garantir a segurança dos dados.
Valide sempre a assinatura
Valide sempre a assinatura
Nunca processe webhooks sem validar a assinatura. Isso protege contra ataques.
Monitore falhas
Monitore falhas
Configure alertas para quando seu endpoint falhar em receber webhooks.
Retry Policy
Se seu endpoint não responder com 2xx, a Garu tentará reenviar com backoff:
Após 6 tentativas sem sucesso (~26h36min de janela total), o webhook é marcado como falho.
Testando Webhooks
Para testar localmente, use ferramentas como:- ngrok - Cria um túnel para seu localhost
- webhook.site - Inspeciona webhooks recebidos
Próximos Passos
Exemplos de Código
Implementações completas em várias linguagens
Solução de Problemas
Resolva erros comuns