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

# Guia de webhooks

> Como o DoglyTdc Pay entrega eventos, como validar a origem e como tratar retentativas.

## Como funciona

Quando algo acontece na conta, o DoglyTdc Pay faz um `POST` JSON para cada webhook ativo inscrito naquele evento.

![Captura de tela: Webhooks no DoglyTdc Pay](https://mintcdn.com/dogly-tdc/qOnot79kPtISSKbW/images/pay/pay-webhooks.png?fit=max\&auto=format\&n=qOnot79kPtISSKbW\&q=85\&s=48fe0748804fa73d5278c4b7b26fb7ea)

Webhooks no DoglyTdc Pay

## Eventos

| Evento | Quando |
| - | - |
| `purchase_approved` | Compra aprovada |
| `pix_generated` | PIX gerado, aguardando pagamento |
| `purchase_refunded` | Reembolso feito |
| `subscription_created` | Assinatura criada |
| `subscription_renewed` | Assinatura renovada |
| `subscription_canceled` | Assinatura cancelada |
| `withdrawal_paid` | Saque pago |
| `withdrawal_failed` | Saque falhou |
| `affiliate_approved` | Afiliado aprovado |

## Formato da entrega

Headers de toda entrega:

| Header | Conteúdo |
| - | - |
| `X-DoglyPay-Event` | Nome do evento |
| `X-DoglyPay-Delivery` | ID único da entrega (use para não processar duas vezes) |
| `X-DoglyPay-Timestamp` | Momento do envio (segundos Unix) |
| `X-DoglyPay-Signature` | `t=<timestamp>,v1=<hmac>` |
| `User-Agent` | `DoglyTdc-Pay-Webhooks/1.0` |

## Validando a origem

A assinatura é um HMAC-SHA256, em hexadecimal, de `"<timestamp>.<corpo cru>"` usando o seu `secret` (`whsec_…`).

```javascript Node.js theme={null}
import crypto from "node:crypto";
export function valid(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1 || ""));
}
```

```python Python theme={null}
import hmac, hashlib, time
def valid(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300: return False
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts.get("v1", ""))
```

> [!WARNING]
>
> Calcule sobre o **corpo cru**, antes de converter para JSON, e recuse entregas com mais de 5 minutos.

## Retentativas

Responda `2xx` em até **10 segundos**. Qualquer outra resposta, redirecionamento ou falha de rede é tentada de novo:

| Tentativa | Espera |
| - | - |
| 2ª | 1 min |
| 3ª | 5 min |
| 4ª | 30 min |
| 5ª | 2 h |
| 6ª | 6 h |
| 7ª | 24 h |

Depois de 7 tentativas a entrega fica como falha. Eventos de teste não são repetidos.

## Regras do endereço

* Só `https://` em domínio público; redirecionamentos não são seguidos.
* Responda rápido e processe em segundo plano.
* Use `X-DoglyPay-Delivery` para ignorar entregas repetidas.


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