Webhook Watches

1 credit per registration

POST /api/premium/watches

The watches endpoint registers a webhook watch. Three types: price (fires on threshold cross or any change), status (fires on provider state transitions), and digest (fires on a daily or weekly cadence with a curated summary regardless of activity). Each watch lives 90 days, fires up to 100 times by default, and delivers HMAC-SHA256 signed POST requests to your callback URL.

When to use this endpoint

When your agent needs realtime notifications instead of polling. Price watches are the canonical "alert me when X drops below Y" pattern; digest watches are set-and-forget periodic summaries.

Parameters

Name	In	Type	Description
spec*	body	object	Watch type discriminator: { type: price \| status \| digest, ... }
callback_url*	body	string	HTTPS URL for signed POST delivery
secret	body	string	Optional HMAC shared secret (recommended)
fire_cap	body	integer	Max fires before auto-disable (1-1000, default 100)

* required

Example response

{
  "ok": true,
  "watch": {
    "id": "wat_a1b2c3d4e5f60718a9b0c1d2",
    "spec": { "type": "price", "model": "Claude Opus 4.7", "field": "blended", "op": "lt", "threshold": 30 },
    "callback_url": "https://agent.example.com/hook",
    "expires_at": "2026-07-26T18:00:00Z",
    "fire_count": 0, "fire_cap": 100, "status": "active"
  }
}

Code samples

Python SDK

from tensorfeed import TensorFeed

tf = TensorFeed(token="tf_live_...")
tf.create_watch(
    spec={"type": "price", "model": "Claude Opus 4.7", "field": "blended", "op": "lt", "threshold": 30},
    callback_url="https://agent.example.com/hook",
    secret="any-shared-secret",
)

TypeScript SDK

import { TensorFeed } from 'tensorfeed';

const tf = new TensorFeed({ token: 'tf_live_...' });
await tf.createWatch({
  spec: { type: 'price', model: 'Claude Opus 4.7', field: 'blended', op: 'lt', threshold: 30 },
  callbackUrl: 'https://agent.example.com/hook',
  secret: 'shared-secret',
});

MCP tool

Available via the TensorFeed MCP server as create_price_watch. Add npx -y @tensorfeed/mcp-server to your Claude Desktop or Claude Code MCP config.

FAQ

How are webhooks signed?

Each delivery includes an X-TensorFeed-Signature header containing sha256=<hex> where the hex is HMAC-SHA256 of the request body using the secret you provided at registration. Verify with crypto.timingSafeEqual to prevent timing-side-channel attacks.

What if my callback URL is down when the watch fires?

The fire is logged with last_delivery_status reflecting the HTTP status (or null on network error) and fire_count is incremented. We do not retry. If reliability matters, point the callback URL at a queue or pub/sub.