# Webhooks — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: cc2a4e08
> Fetch this file at: https://uat.finradarapi.com/llms/webhooks.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Webhooks

Automated server-to-server notifications.

### POST {your_webhook_url}

Payload sent when a Sniper Target is hit.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `event_type` (string): Discriminator field. For sniper webhooks: typically `sniper.filing_hit`. Receivers should switch on this field to route to the appropriate handler.
- `occurred_at` (string): ISO 8601 UTC timestamp of the underlying SEC event.
- `delivery_id` (string): Unique webhook-delivery identifier — use for idempotency-key on the receiver (in-flight retries reuse the same delivery_id).
- `target_id` (string (nullable)): Sniper target identifier (when event_type=sniper.*).
- `payload` (object): Event-specific payload. The fields below describe the `sniper.filing_hit` shape.
- `payload.ticker` (string): Canonical hyphen-form ticker the sniper was registered for.
- `payload.issuer_cik` (string): 10-character zero-padded SEC CIK of the filing issuer.
- `payload.accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Use to pull the full filing detail via [GET /api/v1/sec/filings/{accession_number}](/docs/sec-filings/main-api/get-sec-filings-accession-number).
- `payload.form_type` (string): SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `SC 13D`). Will match one of the `form_types` filter values from the original sniper-target creation.
- `payload.filed_at` (string): ISO 8601 UTC SEC filing-acceptance timestamp (the moment EDGAR accepted the filing).
- `payload.filing_url` (string): Direct URL to the filing on EDGAR — `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=...&filenum=...&accession_number=...`. Useful for opening the filing in a browser tab from a notification system.

**Since:** v1.0.0

**Utility:** DIRECTIONAL FLIP: this is NOT an endpoint FinRadar serves — it is a CONTRACT for events FinRadar will SEND to the customer's URL when a configured sniper target hits a matching SEC filing. The customer registers their receiving URL via [POST /api/v1/sniper/targets](/docs/sniper/sniper-module/post-sniper-targets) (`webhook_url` field) or as the account-level default via `/account/settings/webhooks`. FinRadar then makes an HTTP POST to that URL with the event payload documented below. The receiver MUST respond 200 within 10 seconds — non-200 / timeout / connection-error responses trigger up to 3 exponential-backoff retries (10s, 60s, 300s) before the event is dropped (with logged failure, surfaced in [GET /api/v1/account/usage](/docs/account/main-api/get-account-usage)). For high-availability event delivery, prefer the WS streaming endpoints ([/ws/main-api](/docs/main-api/main-api-stream/ws-main-api), [/ws/insider-api](/docs/insiders/insider-api-stream/ws-insider-api), [/ws/13f-live](/docs/13f/13f-live-stream/ws-13f-live)) — push delivery without the customer needing to operate a public-internet webhook receiver.

**Use case:** Automated trading bot execution: customer's sniper target on TSLA fires when a 10-Q lands at SEC EDGAR -> FinRadar POSTs the event payload to the customer's `https://customer.example.com/sniper-callback` -> customer's webhook-handler parses the payload, runs the trading-rule logic (e.g. 'if revenue beats consensus by >5%, place market buy'), and submits the order via their broker API. Also useful for ops dashboards / Slack alerts / CRM events / any 'when X happens, do Y server-side' workflow that needs SEC-filing event triggers.

**Parameters:**
- `event_type` (body, required): Event type discriminator — one of `sniper.filing_hit` (sniper target matched a filing), `sniper.window_expired` (sniper window ended without a hit; only sent when configured), `insider.transaction.created` (Form 4 push, requires WS subscription topic mapping), `13f.holdings.updated` (13F-HR processed; requires WS topic mapping). The bulk of webhook deliveries are `sniper.filing_hit`.
- `occurred_at` (body, required): ISO 8601 UTC timestamp of the underlying SEC event (filing acceptance for `sniper.filing_hit`, NOT the moment FinRadar dispatched the webhook). Use for chronological ordering on the receiver side.
- `delivery_id` (body, required): Unique webhook-delivery identifier — distinct from event_id. Used by FinRadar to track retries; receiver should idempotency-key on this value to dedupe retries (in-flight retries land with the same delivery_id but new HTTP POST).
- `target_id` (body, optional): Sniper target identifier when `event_type=sniper.*`. Echoed from the original [POST /api/v1/sniper/targets](/docs/sniper/sniper-module/post-sniper-targets) creation. Null on non-sniper event types.
- `payload` (body, required): Event-specific payload object. For `sniper.filing_hit`: `{ ticker, issuer_cik, accession_number, form_type, filed_at, filing_url }`. For other event types, see the per-type payload contract below.

**Sample response:**
```json
{
  "event_type": "sniper.filing_hit",
  "occurred_at": "2026-05-02T20:14:32Z",
  "delivery_id": "wd_3K8mPq2nQ4xZ1Y9b",
  "target_id": "tgt_abc123def456",
  "payload": {
    "ticker": "TSLA",
    "issuer_cik": "0001318605",
    "accession_number": "0001318605-26-000038",
    "form_type": "10-Q",
    "filed_at": "2026-05-02T20:14:32Z",
    "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0001318605&accession_number=0001318605-26-000038"
  }
}
```