Webhooks

Xpoz delivers outbound webhooks for tracked-item updates — when new posts, comments, or user activity match a query, user, or subreddit you've added with addTrackedItems.

Status

Beta Webhooks are available on Pro plans and above. Free-tier accounts can use the polling pattern with checkOperationStatus instead — see the MCP tool catalog.

Subscribing

Register an endpoint from the dashboard or via the MCP addTrackedItems tool with a webhook field on the item:

{
  "platform": "twitter",
  "kind": "query",
  "value": "your brand",
  "webhook": {
    "url": "https://your-app.example.com/xpoz",
    "secret": "whsec_...",
    "events": ["item.matched", "item.error"]
  }
}

Event payload

POSTed as application/json; charset=utf-8:

{
  "id": "evt_01J9Z7...",
  "type": "item.matched",
  "created_at": "2026-05-05T12:34:56Z",
  "tracked_item_id": "ti_01J9Z6...",
  "platform": "twitter",
  "data": {
    "post": { "id": "1789...", "text": "...", "author": {...} }
  }
}

Signature verification

Every delivery includes an X-Xpoz-Signature header. The value is t=<timestamp>,v1=<hex-hmac-sha256>. Compute the HMAC over <timestamp>.<raw-body> using your endpoint's signing secret and constant-time-compare. 

// Node.js example
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const [tPart, vPart] = header.split(',');
  const t = tPart.split('=')[1];
  const sig = vPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

Retry policy

AttemptDelay
1immediate
2+30 s
3+5 min
4+30 min
5+2 h
6+12 h

Endpoints must respond within 10 seconds with a 2xx status. After 6 failed deliveries the subscription is paused; the dashboard surfaces the failure and the last error body.

Event types

TypeWhen
item.matchedNew post or comment matches a tracked query/user/subreddit
item.errorTracked item failed to refresh (e.g. user account suspended)
quota.warningAccount is at 80% of its monthly result quota
quota.exceededAccount hit its monthly result quota

Security

Related