Skip to main content

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çõesWebhooks
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

Sempre responda com HTTP 200 rapidamente (menos de 5 segundos) e processe a lógica de forma assíncrona.

Boas Práticas

Retorne HTTP 200 o mais rápido possível (em até 5 segundos). Processe a lógica de negócio de forma assíncrona.
Webhooks podem ser enviados mais de uma vez. Use o ID do evento para evitar processamento duplicado.
Configure seu endpoint com HTTPS para garantir a segurança dos dados.
Nunca processe webhooks sem validar a assinatura. Isso protege contra ataques.
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