Webhooks

1tokens sends a signed POST request to the HTTPS URL you register in the console whenever a subscribed event happens. Create an endpoint on the Webhooks page and tick the events you want; new endpoints take effect within 30 seconds.

Event catalog

Model

API Key

Account

Order

Subscription

Task

Content

Webhook

Payload format

Every event shares one envelope: id (unique event id), type, domain, created_at (ISO 8601 UTC), api_version and data. Inside data keys are snake_case, timestamps end with _at, amounts are decimal strings (_usd / _credits) and absent values are explicit null. The same event may be delivered more than once because of retries, so deduplicate by id.

{  "id": "evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8B",  "type": "model.price.changed",  "domain": "model",  "created_at": "2026-11-04T08:12:33Z",  "api_version": "2026-11-04",  "data": { }}

Request headers

POST https://your-server.example/webhooksContent-Type: application/jsonUser-Agent: Webhooks/1.0X-Event-Id: evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8BX-Event-Type: model.price.changedX-Delivery-Id: 123456X-Timestamp: 1762243953X-Signature: v1=5f1c…

Verifying the signature

Compute HMAC-SHA256 with the secret shown when the endpoint was created over the string X-Timestamp value + . + raw request body, and compare it in constant time with the hex after v1= in X-Signature. Reject requests whose timestamp differs from now by more than 5 minutes. Respond 2xx first and process afterwards; the whole response must finish within 10 seconds.

import { createHmac, timingSafeEqual } from "node:crypto";export function verify(secret, headers, rawBody) {  const ts = headers["x-timestamp"];  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;  const expected = createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");  const given = String(headers["x-signature"]).replace(/^v1=/, "");  return given.length === expected.length && timingSafeEqual(Buffer.from(given, "hex"), Buffer.from(expected, "hex"));}

import hmac, hashlib, timedef verify(secret: str, headers: dict, raw_body: bytes) -> bool:    ts = headers["X-Timestamp"]    if abs(time.time() - int(ts)) > 300:        return False    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()    given = headers["X-Signature"].removeprefix("v1=")    return hmac.compare_digest(given, expected)

func verify(secret string, ts, sig string, body []byte) bool {	t, _ := strconv.ParseInt(ts, 10, 64)	if math.Abs(float64(time.Now().Unix()-t)) > 300 {		return false	}	mac := hmac.New(sha256.New, []byte(secret))	mac.Write([]byte(ts + "."))	mac.Write(body)	expected := hex.EncodeToString(mac.Sum(nil))	return hmac.Equal([]byte(strings.TrimPrefix(sig, "v1=")), []byte(expected))}

Retries and auto-disable

A non-2xx response or no response within 10 seconds counts as a failure. Each delivery is attempted up to 7 times with the delays below; after that it is marked exhausted. An endpoint whose 10 consecutive deliveries are exhausted is disabled automatically and you are notified by email; re-enable it in the console once fixed. Any delivery can be re-sent manually from the console.

Endpoint requirements

The URL must be a publicly reachable HTTPS address; hostnames that resolve to private, loopback or link-local ranges are rejected. Redirects are not followed and at most 64 KB of the response body is read.