Webhooks

Create a webhook

Register a ticker list plus optional filters once; from then on OptionsBell POSTs a signed unusual_activity event to url whenever new unusual contracts matching the filters appear for those tickers.

When it fires. Evaluation runs every 5 minutes during the webhook's active_hours (default 09:00-16:00 America/New_York) and compares the current unusual-activity scan against the contracts you have already been sent, so each contract is delivered once. At most one delivery per notify_interval_min (default 10); contracts that surface during the cooldown are included in the next delivery. The first run after creation only records a baseline and does not deliver - otherwise you would receive everything that is already unusual the moment you register. The same base floor as the app alerts applies (Vol/OI >= 1.5, OI >= 100, premium >= $25,000) plus your optional criteria. Each event carries at most 10 contracts per ticker (highest Vol/OI first); contracts beyond that cap are marked as seen and not delivered later. Deliveries are best-effort push, typically 1-6 minutes after a print appears in our data.

Response. 201 with the webhook and its signing secret (whsec_...), returned exactly once - store it; there is no way to read it again, only to rotate it. Webhooks and app-created alerts share the limit of 10 per subscription (409 LIMIT_REACHED).

URL rules. url must be an absolute https URL (max 2048 characters, no embedded credentials) on a public host: localhost, *.local, *.internal and hosts that resolve to private, loopback, link-local or carrier-grade NAT ranges are rejected with 400 INVALID_URL. Redirects are not followed at delivery time.

License. Deliveries go to the subscriber's own endpoint; the Personal plan's one-person rule applies - do not forward events to others (https://optionsbell.com/terms#api-license).

post/webhooks

Request

  • Base URL: https://optionsbell.com/api/v1
  • URL: https://optionsbell.com/api/v1/webhooks
  • Auth: API key in header X-API-Key

Request body

urlstring uri required

Absolute https URL on a public host, max 2048 characters, no credentials. Validated (including a DNS lookup) at registration.

tickersstring[] required

1-150 tickers, case-insensitive, each matching ^[A-Z][A-Z0-9.\-]{0,9}$ after upper-casing. Duplicates are dropped.

namestring

Display name; defaults to Webhook <n>. Echoed in every event as webhook.name.

notify_interval_min10 | 30 | 60 | 240 | 480 | 1440
is_activeboolean

Example request

{
  "url": "https://example.com/hooks/optionsbell",
  "tickers": [
    "NVDA",
    "TSLA"
  ],
  "active_hours": {
    "start": "09:00",
    "end": "16:00"
  }
}

Response

Webhook created. secret is included in this response only.

idstring required
namestring required
urlstring uri required
tickersstring[] required

Upper-cased, de-duplicated. Max 150.

notify_interval_min10 | 30 | 60 | 240 | 480 | 1440 required

Minimum minutes between two deliveries.

is_activeboolean required

false: not evaluated at all (set via PATCH).

paused_atstring date-time nullable required

Set when the webhook was paused after 20 consecutive failed deliveries; null otherwise. Paused webhooks are still evaluated but not delivered to.

consecutive_failuresinteger required

Failed unusual_activity deliveries in a row; reset to 0 by any successful delivery, a successful test, or a PATCH with url / is_active: true.

last_run_atstring date-time nullable required

Last evaluation (UTC), whether or not anything was delivered.

last_delivered_atstring date-time nullable required

Last successful unusual_activity delivery (UTC). The cooldown (notify_interval_min) counts from here.

created_atstring date-time required
updated_atstring date-time required
secretstring required

HMAC-SHA256 signing secret (whsec_ + 48 hex chars). Shown once - store it.

Example response

{
  "id": "cmg1x2y3z0000abcd12345678",
  "name": "NVDA/TSLA calls",
  "url": "https://example.com/hooks/optionsbell",
  "tickers": [
    "NVDA",
    "TSLA"
  ],
  "active_hours": {
    "start": "09:00",
    "end": "16:00"
  },
  "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978"
}

Changes

No recorded changes to this operation across all 1 revision of this API.