> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos de pagamento

## 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](https://garu.com.br/inicio)

**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

| Evento | Descrição |
| - | - |
| `product.created` | Um novo produto foi criado |
| `product.updated` | Um produto foi atualizado |
| `product.deleted` | Um produto foi desativado |

### Eventos de Transação

| Evento | Descrição |
| - | - |
| `transaction.created` | Uma nova transação foi iniciada |
| `transaction.updated` | Uma transação teve seus dados atualizados |
| `transaction.payment.succeeded` | Pagamento confirmado |
| `transaction.payment.failed` | Pagamento recusado (com `failureCode` normalizado — ver [Códigos de falha](https://docs.garu.com.br/api-reference/webhooks/codigos-de-falha.md)) |
| `transaction.canceled` | Transação cancelada (pelo seller, contrato ou operadora) |
| `transaction.chargeback` | Chargeback registrado pelo emissor |
| `transaction.refunded` | Pagamento estornado |

> [!NOTE]
>
> 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)

| Evento | Descrição |
| - | - |
| `scheduled_charge.created` | Cobrança agendada criada |
| `scheduled_charge.updated` | Dados da série atualizados |
| `scheduled_charge.canceled` | Cobrança avulsa cancelada |
| `scheduled_charge.paid` | Ciclo da série pago (carrega `seriesId` + `cycleNumber`) |
| `scheduled_charge.overdue` | Ciclo entrou em atraso |
| `scheduled_charge.cycle_failed` | Retries de cartão esgotados (carrega `failureCode`, `failureReason`, `gatewayFailureCode`) |
| `scheduled_charge.recurrence_canceled` | Recorrência cancelada (cancela ciclos futuros) |
| `scheduled_charge.cancel_at_period_end_set` | Soft-cancel ativado |
| `scheduled_charge.cancel_at_period_end_cleared` | Soft-cancel revertido |
| `scheduled_charge.payment_method_attached` | Cartão salvo no ciclo 1 |
| `scheduled_charge.payment_method_changed` | Cartão trocado |
| `scheduled_charge.payment_method_cleared` | Cartão removido (DELETE /:id/payment-method) |

### Eventos de Customer (Trial)

| Evento | Descrição |
| - | - |
| `customer.trial_started` | Trial iniciado |
| `customer.trial_converted` | Trial converteu em pagamento |
| `customer.trial_lapsed` | Trial expirou sem pagamento |

### Eventos de Payment Method (Cartão Salvo)

| Evento | Descrição |
| - | - |
| `payment_method.expiring_soon` | Cartão vence em D-30, D-14 ou D-7 (um disparo por estágio) |
| `payment_method.expired` | Cartão venceu — Garu flippou o status para `expired` automaticamente |

### Eventos de Assinatura

| Evento | Quando chega |
| - | - |
| `subscription.created` | A assinatura foi criada. Isso ainda não quer dizer que ela foi paga: confira o `status`. No Pix Automático, ela chega com `waitingPayment`, antes de o cliente autorizar no banco. |
| `subscription.renewed` | Um pagamento da assinatura foi confirmado, o primeiro também. Traz o período pago e o pagamento, em `transaction`. |
| `subscription.payment_failed` | Um pagamento falhou: o cartão foi recusado, ou o banco recusou o débito do Pix Automático. Chega em cada falha, também na que encerra a assinatura. |
| `subscription.updated` | O cancelamento foi agendado para o fim do período (`cancelAtPeriodEnd: true`). |
| `subscription.cancelled` | A assinatura terminou: cancelamento imediato, fim do período de um cancelamento agendado, falhas de pagamento, ou autorização do Pix Automático recusada ou cancelada no banco. |

Pausar e retomar uma assinatura não geram evento.

> [!NOTE]
>
> **[Pix Automático](https://docs.garu.com.br/guias/pix-automatico.md) usa os mesmos eventos do cartão.** Para saber como um pagamento foi feito, olhe o `paymentMethod` da transação: `creditcard` no cartão, `pix_automatic` no Pix Automático.

### Eventos de Checkout Session

| Evento | Descrição |
| - | - |
| `checkout.session.completed` | Pagamento da checkout session foi concluído |
| `checkout.session.expired` | Checkout session expirou sem pagamento |

## Formato do Payload

Todos os webhooks seguem este formato:

```json theme={null}
{
  "id": "evt_1734863400000_k3j9x2",
  "type": "transaction.payment.succeeded",
  "created": 1734863400,
  "data": {
    "object": {
      // O objeto do evento: a transação, a assinatura, o produto...
    }
  },
  "seller_id": 42
}
```

| Campo | O que é |
| - | - |
| `id` | Id do evento. É o mesmo em cada nova tentativa de entrega. |
| `type` | O tipo do evento (veja as tabelas acima). |
| `created` | Quando o evento foi criado, em segundos Unix. |
| `data.object` | O objeto do evento. |
| `seller_id` | Id da sua loja na Garu. |

### Exemplo: Pagamento Confirmado

Num evento `transaction.*`, `data.object` traz todos os campos da transação. Abaixo, um trecho:

```json theme={null}
{
  "id": "evt_1734863400000_k3j9x2",
  "type": "transaction.payment.succeeded",
  "created": 1734863400,
  "data": {
    "object": {
      "id": 456,
      "uuid": "0b7f3c2e-9a41-4d8e-8f6a-2c1d5e7b9a10",
      "galaxPayId": 1234567,
      "celcoinChargeId": 1234567,
      "celcoinTransactionId": null,
      "status": "payedPix",
      "value": "297.00",
      "paymentMethod": "pix",
      "date": "2024-12-22T10:30:00.000Z",
      "customer": {
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "product": {
        "id": 123,
        "name": "Curso de Marketing Digital"
      }
    }
  },
  "seller_id": 42
}
```

Os valores em reais de uma transação ou de uma assinatura chegam como texto, com duas casas: `"297.00"`.

### Os ids da Celcoin numa transação

| Campo | O que é |
| - | - |
| `celcoinChargeId` | O id da **cobrança** na Celcoin. Vem preenchido numa venda avulsa, num checkout, numa parcela de carnê e numa cobrança agendada. |
| `celcoinTransactionId` | O id do **pagamento** na Celcoin. Vem preenchido num pagamento de uma assinatura da Celcoin. |
| `galaxPayId` | Um dos dois ids acima, conforme o tipo da venda, ou `0` numa venda pela Woovi. Continua no payload por compatibilidade. |

No máximo um dos dois campos novos vem preenchido. Numa venda pela Woovi, os dois vêm `null`.

> [!WARNING]
>
> A Celcoin numera as cobranças e os pagamentos com dois contadores, e os dois repetem os mesmos
> números. O mesmo `galaxPayId` pode ser a cobrança de uma venda e o pagamento de outra. Para achar
> uma venda, use o `id` ou o `uuid` da Garu, ou o campo da Celcoin do tipo certo.

### Exemplo: Pagamento de Assinatura

Num evento `subscription.*`, `data.object` traz os campos da assinatura. O `subscription.renewed` traz também `renewedAt`, `billingCycle` e o pagamento, em `transaction`. Abaixo, um trecho:

```json theme={null}
{
  "id": "evt_1763145000000_r4n3w8",
  "type": "subscription.renewed",
  "created": 1763145000,
  "data": {
    "object": {
      "id": 100,
      "uuid": "6f1c2a9e-3b7d-4e8a-9c41-2d5f7b8e0a13",
      "status": "active",
      "amount": "49.90",
      "currentPeriodStart": "2025-11-14T18:30:00.000Z",
      "currentPeriodEnd": "2025-12-14T18:30:00.000Z",
      "cancelAtPeriodEnd": false,
      "retryCount": 0,
      "renewedAt": "2025-11-14T18:30:02.000Z",
      "billingCycle": 2,
      "transaction": {
        "id": 4321,
        "value": "49.90",
        "status": "captured"
      }
    }
  },
  "seller_id": 42
}
```

Libere o acesso no `subscription.renewed`, até o `currentPeriodEnd`. Num `subscription.payment_failed`, a assinatura traz `status: past_due`, o número de falhas em `retryCount` e a última mensagem de erro em `lastBillingError`.

### Exemplo: Produto Criado

```json theme={null}
{
  "id": "evt_1734863400000_p8q2m1",
  "type": "product.created",
  "created": 1734863400,
  "data": {
    "object": {
      "id": 123,
      "name": "Curso de Marketing Digital",
      "value": 297.00,
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  },
  "seller_id": 456
}
```

### Exemplo: Checkout Session Concluída

```json theme={null}
{
  "id": "evt_1734877800000_c4n7z0",
  "type": "checkout.session.completed",
  "created": 1734877800,
  "data": {
    "object": {
      "id": "cs_ABC123xyz",
      "status": "complete",
      "transaction_id": 789,
      "metadata": {
        "order_id": "12345"
      },
      "client_reference_id": "order_abc123",
      "completed_at": "2024-12-22T14:30:00.000Z"
    }
  },
  "seller_id": 42
}
```

### Exemplo: Checkout Session Expirada

```json theme={null}
{
  "id": "evt_1734955200000_e2x5w8",
  "type": "checkout.session.expired",
  "created": 1734955200,
  "data": {
    "object": {
      "id": "cs_DEF456uvw",
      "status": "expired",
      "metadata": {
        "order_id": "67890"
      },
      "client_reference_id": "order_def456",
      "expires_at": "2024-12-23T12:00:00.000Z"
    }
  },
  "seller_id": 42
}
```

## Validando Assinaturas

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

<Snippet file="snippets/webhook-validation.mdx" />

## Boas Práticas

> [accordion] 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.

> [accordion] Implemente idempotência
>
> Webhooks podem ser enviados mais de uma vez. Use o ID do evento para evitar processamento duplicado.

> [accordion] Use HTTPS
>
> Configure seu endpoint com HTTPS para garantir a segurança dos dados.

> [accordion] Valide sempre a assinatura
>
> Nunca processe webhooks sem validar a assinatura. Isso protege contra ataques.

> [accordion] Monitore falhas
>
> A Garu avisa por e-mail quando um endpoint falha 4 vezes seguidas (veja [Aviso por e-mail](#aviso-por-e-mail)). Configure também alertas no seu sistema para quando o seu endpoint falhar em receber webhooks.

## Retry Policy

Se seu endpoint não responder com 2xx, a Garu tentará reenviar com backoff:

| Nova tentativa | Intervalo desde a anterior |
| - | - |
| 1 | 1 minuto |
| 2 | 5 minutos |
| 3 | 30 minutos |
| 4 | 2 horas |
| 5 | 8 horas |
| 6 | 16 horas |

A primeira entrega acontece na hora. Com as 6 novas tentativas, são 7 no total, e o campo `attempts` do evento vai até `7`. Se todas falharem (\~26h36min de janela total), o webhook é marcado como falho (`failed`), e você pode [reenviá-lo](https://docs.garu.com.br/guias/reenviar-webhook.md).

> [!NOTE]
>
> Até a v0.35.0, a Garu desistia de um evento depois de \~10h36min: a nova tentativa de 16 horas não acontecia.

### Aviso por e-mail

Quando a 4ª tentativa de entregar um evento falha (cerca de 36 minutos depois da primeira), a Garu manda um e-mail para o dono da loja e para os membros da equipe que podem editar webhooks. O e-mail mostra o endereço, a última resposta do seu endpoint e quantos eventos esperam nova tentativa. Enquanto o endpoint continuar falhando, a Garu manda no máximo um e-mail por dia para cada endpoint.

A Garu não desativa o endpoint sozinha. Para não receber o aviso, desligue **Webhook com falha** em **Configurações → Notificações**.

Se você desativar um endpoint, a Garu pausa as entregas dele. Os eventos que esperavam nova tentativa voltam a ser entregues se você reativar o endpoint.

## Testando Webhooks

Para testar localmente, use ferramentas como:

* [ngrok](https://ngrok.com/) - Cria um túnel para seu localhost
* [webhook.site](https://webhook.site/) - Inspeciona webhooks recebidos

```bash theme={null}
# Usando ngrok
ngrok http 3000

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

## Próximos Passos

> [card] [Exemplos de Código](https://docs.garu.com.br/api-reference/exemplos.md)
>
> Implementações completas em várias linguagens

> [card] [Solução de Problemas](https://docs.garu.com.br/api-reference/troubleshooting.md)
>
> Resolva erros comuns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.