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

# Webhooks

> Get notified when money moves: top-ups, gift redemptions, and low balance.

TokenGift can POST signed events to your endpoint when your wallet changes.

<Note>Webhook endpoint management UI is rolling out. Contact [support@tokengift.ai](mailto:support@tokengift.ai) to register an endpoint in the meantime.</Note>

## Events

| Event             | Fires when                                      |
| ----------------- | ----------------------------------------------- |
| `topup.completed` | A top-up purchase lands in your wallet          |
| `gift.redeemed`   | A gift code is redeemed into your wallet        |
| `balance.low`     | Balance drops below the threshold (default 20%) |

## Payload

```json theme={null}
{
  "id": "obx_9f2k…",
  "type": "topup.completed",
  "created": "2026-07-29T05:00:00.000Z",
  "data": {
    "event": "topup.completed",
    "amount": "5.00",
    "expires_at": "2026-12-26"
  }
}
```

## Verifying signatures

Every delivery includes a `TokenGift-Signature` header:

```
TokenGift-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with your endpoint secret>
```

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
  return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
```

## Retries

Failed deliveries are retried with exponential backoff for roughly 24 hours, then marked
failed. Respond with any `2xx` quickly (do heavy work async) to avoid retries.