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

EventoDescrição
product.createdUm novo produto foi criado
product.updatedUm produto foi atualizado
product.deletedUm produto foi desativado

​
Eventos de Transação

EventoDescrição
transaction.createdUma nova transação foi iniciada
transaction.paidPagamento confirmado
transaction.failedPagamento falhou
transaction.refundedPagamento estornado
transaction.cancelledTransação cancelada

​
Eventos de Assinatura

EventoDescrição
subscription.createdNova assinatura criada
subscription.activatedAssinatura ativada
subscription.pausedAssinatura pausada
subscription.cancelledAssinatura cancelada
subscription.renewedAssinatura renovada

​
Eventos de Checkout Session

EventoDescrição
checkout.session.completedPagamento da checkout session foi concluído
checkout.session.expiredCheckout session expirou sem pagamento

​
Formato do Payload

Todos os webhooks seguem este formato: 
{
  "event": "transaction.paid",
  "timestamp": "2024-12-24T10:30:00.000Z",
  "data": {
    // Dados específicos do evento
  }
}

​
Exemplo: Pagamento Confirmado

{
  "event": "transaction.paid",
  "timestamp": "2024-12-24T10:30:00.000Z",
  "data": {
    "id": 456,
    "productId": 123,
    "productName": "Curso de Marketing Digital",
    "value": 297.00,
    "paymentMethod": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "123.456.789-00"
    },
    "paidAt": "2024-12-24T10:30:00.000Z"
  }
}

​
Exemplo: Produto Criado

{
  "event": "product.created",
  "timestamp": "2024-12-24T10:30:00.000Z",
  "data": {
    "id": 123,
    "name": "Curso de Marketing Digital",
    "value": 297.00,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sellerId": 456
  }
}

​
Exemplo: Checkout Session Concluída

{
  "event": "checkout.session.completed",
  "timestamp": "2024-12-24T14:30:00.000Z",
  "data": {
    "id": "cs_ABC123xyz",
    "status": "complete",
    "product_id": 123,
    "transaction_id": 789,
    "customer_email": "joao@email.com",
    "metadata": {
      "order_id": "12345"
    },
    "client_reference_id": "order_abc123",
    "completed_at": "2024-12-24T14:30:00.000Z"
  }
}

​
Exemplo: Checkout Session Expirada

{
  "event": "checkout.session.expired",
  "timestamp": "2024-12-25T12:00:00.000Z",
  "data": {
    "id": "cs_DEF456uvw",
    "status": "expired",
    "product_id": 123,
    "metadata": {
      "order_id": "67890"
    },
    "client_reference_id": "order_def456",
    "expires_at": "2024-12-25T12:00:00.000Z"
  }
}

​
Validando Assinaturas

Para garantir que o webhook veio da Garu, valide a assinatura:

​
Validando Assinatura do Webhook

const crypto = require('crypto');

function validarAssinatura(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Uso no Express.js
app.post('/webhooks/garu', (req, res) => {
  const signature = req.headers['x-garu-signature'];

  if (!validarAssinatura(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  res.status(200).json({ received: true });
  // Processar evento de forma assíncrona...
});
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:
TentativaIntervalo
1ª retry5 minutos
2ª retry30 minutos
3ª retry2 horas
4ª retry8 horas
5ª retry24 horas
Após 5 tentativas sem sucesso, 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
# Usando ngrok
ngrok http 3000

# Seu endpoint público será algo como:
# https://abc123.ngrok.io/webhooks/garu

​
Próximos Passos

Exemplos de Código

Implementações completas em várias linguagens

Solução de Problemas

Resolva erros comuns