> ## 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.

# Guía de webhooks

> Cómo DoglyTdc Pay entrega eventos, cómo validar el origen y cómo manejar los reintentos.

## Cómo funciona

Cuando ocurre algo en la cuenta, DoglyTdc Pay realiza un `POST` JSON a cada webhook activo suscrito a ese evento.

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

Webhooks en DoglyTdc Pay

## Eventos

| Evento | Cuándo |
| - | - |
| `purchase_approved` | Compra aprobada |
| `pix_generated` | PIX generado, esperando pago |
| `purchase_refunded` | Reembolso realizado |
| `subscription_created` | Suscripción creada |
| `subscription_renewed` | Suscripción renovada |
| `subscription_canceled` | Suscripción cancelada |
| `withdrawal_paid` | Retiro pagado |
| `withdrawal_failed` | Retiro fallido |
| `affiliate_approved` | Afiliado aprobado |

## Formato de la entrega

Headers de cada entrega:

| Header | Contenido |
| - | - |
| `X-DoglyPay-Event` | Nombre del evento |
| `X-DoglyPay-Delivery` | ID único de la entrega (úselo para no procesar dos veces) |
| `X-DoglyPay-Timestamp` | Momento del envío (segundos Unix) |
| `X-DoglyPay-Signature` | `t=<timestamp>,v1=<hmac>` |
| `User-Agent` | `DoglyTdc-Pay-Webhooks/1.0` |

## Validando el origen

La firma es un HMAC-SHA256, en hexadecimal, de `"<timestamp>.<cuerpo en bruto>"` usando su `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 el **cuerpo en bruto**, antes de convertir a JSON, y rechace entregas con más de 5 minutos.

## Reintentos

Responda `2xx` en un máximo de **10 segundos**. Cualquier otra respuesta, redirección o falla de red se volverá a intentar:

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

Después de 7 intentos, la entrega se marca como fallida. Los eventos de prueba no se repiten.

## Reglas de la dirección

* Solo `https://` en dominio público; no se siguen las redirecciones.
* Responda rápido y procese en 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.