Push Subscriptions (Webhooks)

​

Two doors, two products

​

Filters

• symbols — only rows whose payload symbols include one of these tickers (case-insensitive).
• company_ids — only rows whose payload company_id is one of these.
• label_families — only rows carrying one of these label families, such as earnings, guidance or merger_acquisition. See Event labels.

​

Where delivery starts

​

The signing secret is shown once

​

What a delivery looks like

• Content-Type: application/json
• X-FA-Signature: t=<unix seconds>,v1=<hex> — the signature, described below.
• X-FA-Subscription — the subscription id.

{
  "subscription_id": "3f6d2a9e-8c1b-4e0f-9a51-6b7c2d4e8f10",
  "stream": "merged",
  "rows": [
    { "seq": 2308415, "payload": { "event_id": "AAPL:earnings:20260730", "revision": 2 } }
  ],
  "next_after_seq": 2308415
}

​

Verify the signature

1. Parse t and v1 from X-FA-Signature.
2. Reject the delivery if t is more than 5 minutes from your current time. This stops a captured delivery from being replayed later.
3. Compute the HMAC over <t>.<raw body> and compare it with v1 using a constant-time comparison.

import { createHmac, timingSafeEqual } from "crypto";

function verify(secret: string, header: string, rawBody: string): boolean {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header.trim());
  if (!match) return false;
  const t = Number(match[1]);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(match[2], "hex");
  return expected.length === received.length && timingSafeEqual(expected, received);
}

​

Delivery semantics

• At-least-once. The same row can arrive more than once. Dedupe events-door rows on (event_id, revision) and news-door rows on the payload’s id; both are stable across re-deliveries.
• In order. A subscription’s position is one integer, cursor_seq. Delivery never skips ahead after a failure, so order per subscription is preserved and a retry resumes exactly where delivery stopped.
• Filtered rows still move the cursor. cursor_seq tracks position in the log, not the last row delivered to you.
• Freshness is about 2 minutes end to end, because the log is written in 2-minute cycles. Push removes polling; it does not make the underlying data arrive sooner.

​

Failures and suspension

​

Limits

​

POST /v1/events/subscriptions

​

GET /v1/events/subscriptions

​

DELETE /v1/events/subscriptions/{id}

​

POST /v1/events/subscriptions/{id}/resume

​

The live stream instead of webhooks

​

Related pages

curl -X POST "https://api.focusalpha.ai/v1/events/subscriptions" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/focusalpha",
    "symbols": ["AAPL", "NVDA"],
    "label_families": ["earnings", "guidance"]
  }'

curl "https://api.focusalpha.ai/v1/news/subscriptions" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

curl -X DELETE "https://api.focusalpha.ai/v1/events/subscriptions/3f6d2a9e-8c1b-4e0f-9a51-6b7c2d4e8f10" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

curl -X POST "https://api.focusalpha.ai/v1/events/subscriptions/3f6d2a9e-8c1b-4e0f-9a51-6b7c2d4e8f10/resume" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "id": "3f6d2a9e-8c1b-4e0f-9a51-6b7c2d4e8f10",
  "url": "https://example.com/hooks/focusalpha",
  "stream": "merged",
  "symbols": ["AAPL", "NVDA"],
  "company_ids": null,
  "label_families": ["earnings", "guidance"],
  "active": true,
  "cursor_seq": 2308414,
  "consecutive_failures": 0,
  "suspended_at": null,
  "suspended_reason": null,
  "created_at": "2026-10-14T09:30:00.000Z",
  "secret": "whsec_…"
}

{
  "subscriptions": [
    {
      "id": "8a1c4e2b-5d6f-4a7b-9c0d-1e2f3a4b5c6d",
      "url": "https://example.com/hooks/news",
      "stream": "raw",
      "symbols": null,
      "company_ids": null,
      "label_families": ["merger_acquisition"],
      "active": true,
      "cursor_seq": 2308101,
      "consecutive_failures": 25,
      "suspended_at": "2026-10-12T04:10:00.000Z",
      "suspended_reason": "suspended after 25 consecutive delivery failures; resume to retry from cursor 2308101",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}