Price Webhooks

​

A webhook

• Its id: yours (1 to 64 characters among A-Z a-z 0-9 _ . : -, not starting with a dot), or one we generate when you create it without one (wh_ + 16 hex characters). Ids are private to your account.
• Its URL (callbackUrl): https:// on the default port (443), a public host, no credentials, up to 2,048 characters. We check it when you create the webhook and when you change it. Redirects are never followed: register the final URL.
• Its secret: every message is signed with it (verify the signature). Send your own (16 to 256 printable ASCII characters, no spaces) or let us generate one (whsec_…): a generated secret is returned once, in the response that created it, and never shown again. Replace it at any time with /endpoint (rotate: true generates a new one).
• Create it, optionally with its first triggers. Creating an id you already have adds the triggers to it, as long as the URL (and the secret and name, when you send them) are the same; a different one answers 400. If you lost the response of a creation that generated your secret, rotate it with /endpoint.

​

Triggers

• id: yours (same rule as a webhook id), or generated (tr_ + 16 hex characters). Unique within its webhook: an id stays taken for 30 days after its trigger ends. Re-sending the same trigger (same id, token and condition) changes nothing and comes back in alreadyIn with its status, so adding is safe to retry. A trigger you removed stays removed: sending it again comes back in alreadyIn with status: "removed" and is not armed; arm it again under a new id.
• name: optional, 1 to 128 characters, sent back in the message.
• chain and address: the token (solana or evm:<id>; EVM addresses are lowercased, Solana mints kept as they are).
• priceUsd or priceNative, one of the two: one operator and its level, in USD or in the chain’s native coin, as a decimal string ("0.0024", at most 32 characters) or a JSON number. Every response and message gives the trigger’s unit (usd or native).

​

Conditions

• eq takes its side when you create the trigger: if the token’s price in the level’s unit (the priceUsd or priceNative of /v1/token/price at that moment) is at or below the level, the trigger fires when the price reaches the level (direction: "gte"); if it is above, when it comes down to it (direction: "lte"). Every response and message gives the direction. A token with no price yet in that unit cannot take eq (rejected, details.reason: "noPrice"): use gte or lte.
• Only a live price counts. A trigger is never judged on a bonding curve’s last price once the token has moved to a new market. Until the token’s new market has a price, armed triggers wait and a new eq is refused (noPrice). While /v1/token/price does not return the token, a new trigger on it comes back NOT_FOUND, whatever its condition.
• A condition already true fires at once. A take-profit set below the current price fires within seconds.

​

USD or native

• priceUsd judges the token’s USD price: its native price times the native coin’s USD price, the same priceUsd as /v1/token/price. It moves when the token trades and when the native coin moves: if SOL drops 10%, a token priced in SOL is worth 10% fewer dollars, and a USD stop-loss on it fires even if the token did not trade. Use it when your app and your users count in dollars.
• priceNative judges the token against its chain’s native coin only: a move of the native coin never fires it. Use it to follow a token’s own performance.
• A USD level is judged on a current native coin price only: without one, USD triggers wait, they never fire on an old price. A sudden move of more than 5% in the native coin’s USD price is taken once the next reading confirms it (about 10 seconds on Solana, about a minute on EVM chains), so a single bad print never fires USD levels.

​

Which tokens

​

The message

{
  "type": "price.reached",
  "eventId": "evt_7c1e9a2b0d3f4e5a8b6c9d0e1f2a3b4c",
  "webhookId": "tpsl",
  "triggerId": "order-8812",
  "name": "TP x2",
  "data": {
    "chain": "solana",
    "address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "condition": { "gte": "0.000023" },
    "unit": "usd",
    "direction": "gte",
    "priceNative": "0.000000121",
    "priceUsd": "0.0000230142",
    "pool": "Hs97TCZeuYiJxooo3U73qEHXg3dKpRL4uYKYRryEK9CF",
    "at": 1792541400000
  }
}

• condition is the operator and level you set (eq kept), unit its unit (usd or native), direction the side it is watched from.
• priceUsd and priceNative are the token’s price when it met the condition, in USD and in the native coin; the one of the trigger’s unit is the price that met it. priceUsd is always set on a USD level; on a native level it is null if the native coin’s USD price was not available at that moment. pool is the market the price was read on, at when it was observed (unix ms).
• Headers: Content-Type: application/json, User-Agent: Serialized-Webhooks/1, X-Serialized-Event: <eventId> and X-Serialized-Signature.

​

Verify the signature

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, rawBody, header, toleranceSec = 300) {
  if (typeof header !== 'string') return false;
  const parts = Object.fromEntries(header.split(',').map((kv) => [kv.slice(0, kv.indexOf('=')), kv.slice(kv.indexOf('=') + 1)]));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'));
  const given = Buffer.from(parts.v1 ?? '');
  return expected.length === given.length && timingSafeEqual(expected, given);
}

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str, tolerance_sec: int = 300) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

​

Delivery and retries

• Answer with a 2xx within 5 seconds. Do the work after answering: a slower answer counts as a failed attempt.
• Retries: an attempt that does not get a 2xx is retried 5 seconds, 30 seconds and 2 minutes after the first one (4 attempts in all). The body is the same at every attempt; only the signature’s t changes. A redirect counts as a failure.
• A host that does not resolve is retried the same way. Nothing goes out to your URL, so nothing is billed for it (credits).
• A URL refused by our checks when we send (the URL, or the address its host resolves to, is a private address) is not retried: the trigger ends as failed (url_refused).
• At least once: the same message can arrive twice. Process each eventId once.
• Within 5 minutes: a delivery that has not got its 2xx 5 minutes after the trigger is taken for delivery stops, and the trigger ends as failed (expired).
• A trigger whose delivery does not succeed ends as failed. Read what happened with list triggers (delivery.attempts, lastStatus, lastError).
• Change the URL or the secret with /endpoint: the next attempts use the new ones.

​

Statuses

​

Limits

​

Credits

​

Test your endpoint