Webhooks

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

Webhook endpoint management UI is rolling out. Contact support@tokengift.ai to register an endpoint in the meantime.

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

{
  "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>

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.

Handle an empty wallet Models & pricing

⌘I

Get Started

Guides

Reference

Events

Payload

Verifying signatures

Retries

​Events

​Payload

​Verifying signatures

​Retries

Events

Payload

Verifying signatures

Retries