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

# Webhooks guide

> How DoglyTdc Pay delivers events, how to validate the origin, and how to handle retries.

## How it works

When something happens in the account, DoglyTdc Pay makes a JSON `POST` to each active webhook subscribed to that event.

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

Webhooks in DoglyTdc Pay

## Events

| Event | When |
| - | - |
| `purchase_approved` | Purchase approved |
| `pix_generated` | PIX generated, awaiting payment |
| `purchase_refunded` | Purchase refunded |
| `subscription_created` | Subscription created |
| `subscription_renewed` | Subscription renewed |
| `subscription_canceled` | Subscription canceled |
| `withdrawal_paid` | Withdrawal paid |
| `withdrawal_failed` | Withdrawal failed |
| `affiliate_approved` | Affiliate approved |

## Delivery format

Headers for every delivery:

| Header | Content |
| - | - |
| `X-DoglyPay-Event` | Event name |
| `X-DoglyPay-Delivery` | Unique delivery ID (use to prevent processing twice) |
| `X-DoglyPay-Timestamp` | Delivery timestamp (Unix seconds) |
| `X-DoglyPay-Signature` | `t=<timestamp>,v1=<hmac>` |
| `User-Agent` | `DoglyTdc-Pay-Webhooks/1.0` |

## Validating the origin

The signature is a hex-encoded HMAC-SHA256 of `"<timestamp>.<raw body>"` using your `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]
>
> Compute over the **raw body**, before parsing to JSON, and reject deliveries older than 5 minutes.

## Retries

Respond with `2xx` within **10 seconds**. Any other response, redirect, or network failure is retried:

| Attempt | Wait time |
| - | - |
| 2nd | 1 min |
| 3rd | 5 min |
| 4th | 30 min |
| 5th | 2 h |
| 6th | 6 h |
| 7th | 24 h |

After 7 attempts, the delivery is marked as failed. Test events are not retried.

## Endpoint rules

* Only `https://` on a public domain; redirects are not followed.
* Respond quickly and process in the background.
* Use `X-DoglyPay-Delivery` to ignore duplicate deliveries.


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