Skip to content
FalsifyLab FalsifyLab Alpha MCP

Receive signals via webhooks (paid plan)

Receive signals via webhooks (paid plan)

Webhooks push events to your URL the moment FalsifyLab generates them. No polling, no missed firings. paid plan only.

What gets pushed

eventwhen
confluence.detecteda new asset hits 2+ signal alignment
insider_cluster.new3+ insiders bought the same ticker in 24h
sec8k.materialnew 8-K with material item code (2.02, 5.02, 2.01, etc)
etf_flow.spikespot BTC or ETH ETF flow jumps above threshold

Pick a subset or pass ["*"] for all.

Register

Terminal window
curl -X POST https://falsifylab.com/api/webhooks \
  -H "Authorization: Bearer <your-whop-license-or-oauth-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/falsifylab-webhook",
    "events": ["confluence.detected", "insider_cluster.new"],
    "label": "prod-trading-bot"
  }'

Response (you only see the secret ONCE; save it):

{
  "id": "wh_a1b2c3d4e5f6",
  "url": "https://yourapp.com/falsifylab-webhook",
  "events": ["confluence.detected", "insider_cluster.new"],
  "secret": "whsec_..."
}

Receive

Every event hits your endpoint as POST with these headers:

X-FL-Event-Id: evt_a1b2c3...
X-FL-Event:    confluence.detected
X-FL-Signature: sha256=<hex>
Content-Type:  application/json
User-Agent:    falsifylab-webhook/1.0

Body:

{
  "id": "evt_a1b2c3...",
  "event": "confluence.detected",
  "created_at": "2026-05-14T03:15:04Z",
  "payload": {
    "asset": "COIN",
    "signal_count": 4,
    "sources": ["insider_cluster", "sec8k_2.02", "etf_inflow_btc", "hl_vault"],
    "composite_score": 0.82
  }
}

Verify signature

import hmac, hashlib


def verify(body_bytes, signature_header, secret):
    expected = "sha256=" + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

If signature does not match: reject + log. Replay attack possible without verification.

List / delete

Terminal window
# list mine
curl -H "Authorization: Bearer <key>" https://falsifylab.com/api/webhooks


# delete one
curl -X DELETE \
  -H "Authorization: Bearer <key>" \
  "https://falsifylab.com/api/webhooks?id=wh_a1b2c3d4e5f6"

Delivery semantics

  • POST timeout: 8s. Non-2xx response = delivery failure.
  • Retry policy: best-effort. v1 fires once; no automatic retry yet (planned).
  • Idempotency: use the id field. Each event has a unique id even across redelivery.
  • Subscriber cap: 10 webhooks per account.

Limits

  • Free tier: no webhook access (registration returns 401).
  • paid plan: 10 webhooks, all event types, no rate limit on delivery (we limit on our side based on data generation cadence).