What a webhook is, and why your options alerts should use one

You already use webhooks every day without calling them that. Pay with a card and a receipt lands in a chat channel. Push a commit and a build starts. Somebody fills in a form and a row appears in a spreadsheet. In each case one service told another service that something happened, the moment it happened, by sending a small message to an address the receiver had handed over in advance. That message is a webhook.

OptionsBell now does the same thing for unusual options activity. You register the tickers you care about and an https address you control. When new unusual contracts show up on those tickers, we send the contracts to that address as JSON. No refreshing, no polling loop, no inbox. This post explains what that means in practice if you are a trader rather than a software engineer, and what you need on your side to use it.

The three ways an alert can reach you

Every alerting product picks one or more of the same three delivery models. They differ in who does the asking and what has to be running on your end.

Polling is the one most people build first because it is easy to reason about: a cron job asks the options flow API every five minutes whether anything new happened. It works, and it burns requests to find out that nothing changed. On a normal day most of those calls return the same rows as the call before. A webhook inverts the relationship. You do not ask. We tell you, and only when there is something to tell.

What an OptionsBell webhook actually does

A webhook on OptionsBell is a saved search plus an address. You create it once through the API with a ticker list of up to 150 symbols, optional filters (calls only, minimum premium, maximum days to expiry, minimum Vol/OI and so on), a delivery cooldown and an active window in New York time. From then on:

• Every 5 minutes inside your active hours we run the unusual options scan for your tickers against your filters.
• We compare the result with the contracts you have already received. Only contracts you have not seen yet are delivered, so each contract arrives exactly once, even if it stays unusual for a week.
• If anything is new, we POST a JSON event to your URL. An event carries up to 10 contracts per ticker, highest Vol/OI first.
• If nothing is new, nothing is sent. Quiet tickers stay quiet.

The very first run after you create a webhook only records a baseline and sends nothing. Otherwise you would receive everything that is already unusual the second you register, which is a wall of noise, not a signal. Expect your first real event ten minutes or more after creation, and only if the tape produces something new.

A delivery looks like this. Numbers are JSON numbers, dates are ISO strings, and each contract carries the fields you would use to decide whether it matters:

POST https://your-server.example/hooks/optionsbell
X-OptionsBell-Event: unusual_activity
X-OptionsBell-Delivery: whd_3f9c1a2b4d5e6f708192a3b4
X-OptionsBell-Signature: t=1756912502,v1=5257a869e7ec...

{
  "event": "unusual_activity",
  "delivery_id": "whd_3f9c1a2b4d5e6f708192a3b4",
  "sent_at": "2026-09-03T14:35:02.117Z",
  "data_date": "2026-09-03",
  "webhook": { "id": "cmg1x2y3z0000abcd12345678", "name": "NVDA/TSLA calls" },
  "count": 1,
  "contracts": [
    {
      "symbol": "NVDA",
      "option_symbol": "NVDA|20261016|215.00C",
      "symbol_type": "Call",
      "strike_price": "215.0000",
      "expiration_date": "10/16/26",
      "days_to_expiration": 43,
      "volume_oi_ratio": 85.3,
      "volatility": 54,
      "premium_estimate": 13700000
    }
  ]
}

Do I need to be a programmer?

You need somewhere for that POST to land. That is the honest requirement, and it is smaller than it sounds. Three options, from least to most technical:

• A no-code automation tool. n8n, Make, Zapier and Pipedream all give you a catch-hook URL that accepts a POST and lets you route the fields into Slack, a spreadsheet, Notion or a message to yourself. Setup time is minutes.
• A serverless function. A Cloudflare Worker or a Vercel route is a file with a few lines in it. It receives the event, checks the signature and forwards the contracts wherever you want them. Free tiers cover this comfortably.
• Your own server. If you already run a bot or a research box, add one route to it. That is the case for most people who ask for webhooks in the first place.

Registering the webhook itself is one API call. No dashboard, no form, which is deliberate: the people who want push delivery are the people who script things.

curl -X POST https://optionsbell.com/api/v1/webhooks \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Watchlist calls",
    "url": "https://your-server.example/hooks/optionsbell",
    "tickers": ["NVDA", "TSLA", "AMD", "AVGO"],
    "criteria": { "type": "c", "min_premium": 250000, "max_dte": 45 },
    "notify_interval_min": 10
  }'

How you know a delivery is really from us

Anyone who learns your URL could send a fake event to it. To make that useless, every delivery is signed. When you create the webhook you get a secret back, shown exactly once. Each POST carries a header with a timestamp and an HMAC-SHA256 code computed from that timestamp, the exact request body and your secret. Your receiver recomputes the code and drops the request if it does not match or if the timestamp is stale. The docs have copy-paste verification code for Node and Python; it is ten lines either way.

Two more small things make automation reliable. Each delivery has an id that stays the same across retries, so you can ignore a duplicate if we retry and both attempts get through. And there is a test endpoint that sends one signed sample event through the real delivery path, so you can confirm your receiver works before the market gives you a live one.

What happens when your endpoint is down

Servers restart, laptops close, free tiers hiccup. The delivery rules are built for that. We try up to three times per delivery: immediately, after two seconds and after six. Any 2xx answered within five seconds counts as delivered. If all three attempts fail, the contracts stay marked as not yet delivered and go out again with the next five-minute run. After 20 failed deliveries in a row the webhook pauses itself so it does not hammer a dead address; you resume it with a single update call or a successful test, and a delivery log shows you every attempt with its HTTP status and error text.

What it costs and where it fits

Webhooks are part of the Personal plan, the same $24.99 per month that covers email alerts, the REST API and the MCP server. Outbound deliveries do not count against the API rate limits; only the handful of management calls you make to create or edit a webhook do. Webhooks and app alerts share one pool of ten per subscription, each with up to 150 tickers.

Email alerts stay the right tool if you want to read and decide yourself. Polling with the since parameter stays the right tool for an audit trail or a backfill after downtime, because a webhook tells you about new contracts as they appear and does not replay history. For anything that should react on its own the moment a print shows up, the webhook is the piece that was missing.

If you want to see what people actually build on it, read seven things to build on an options flow webhook. If you want to understand why a flow webhook behaves differently from the price alerts your broker offers, that is this post.