Skip to content
Searches page titles, headings, and route paths. Press slash to focus.

Webhooks reference

What endpoints and subscriptions accept, how verification and signatures work, and what happens when a delivery fails. To set up your first webhook, follow Set up webhooks.

Endpoints

POST /v3/callbacks/endpoints creates an endpoint. It takes url, event_types, and an optional description, and answers 201. The url must be:

  • https, on port 443;
  • a public DNS name that resolves to a public address.

These are refused:

  • IP addresses;
  • user names and passwords in the URL;
  • localhost;
  • names under .local or .internal.

Source address: deliveries come from 67.227.64.202, over IPv4.

event_types lists the events the endpoint receives:

EventWhen
filing.newA new filing matches a subscription. data.filing is the filing.
filing.updatedA filing already sent changes: documents added or fetched again, made final by the nightly feed, merged with a redelivery, or linked to the filing it amends. data.change says which. Sent to subscriptions with include_corrections.
filing.correctedSEC corrects a filing already sent. data.changes lists the header fields and documents that changed. Sent to subscriptions with include_corrections.
filing.digestThe filing.new events of a subscription with min_interval_s, gathered over its interval: data.events, data.count, and data.truncated.
endpoint.verificationThe endpoint's challenge (see below). Sent to every endpoint, whatever its event_types.

Subscriptions

POST /v3/search/subscriptions creates a subscription. It takes name, query, and endpoint_id. query is a JSON object with the filters of GET /v3/search:

  • forms or form_families: a form type with its variants, such as 10-K, which also matches 10-K/A.
  • form_types: the exact form type, such as 10-K/A.
  • ciks and tickers: companies. Tickers are resolved to CIKs when the subscription is saved.
  • sics: SIC industry codes.
  • states and inc_states: the state of the business address, and the state of incorporation.
  • items: 8-K item codes.
  • A filter subscription has at least one filter and receives the new filings that match.
  • A firehose subscription has no filter and receives every new filing.

Both send filing.new, so the endpoint must list it in event_types.

  • include_corrections true also sends filing.updated and filing.corrected for the filings the subscription has sent.
  • min_interval_s sends at most one request per interval. The events of the interval arrive together as one filing.digest.
  • A subscription receives new filings, so a filing-date window (filed_from, filed_to) or status in the query gets 400, naming it.
  • A subscription matches filings by their filing-level fields, so q, doctypes, primary_only=true, or entityName in the query gets 400 invalid_parameter, naming that parameter.
  • POST /v3/search/subscriptions/{id}/test answers with the events the subscription would have sent for recent filings, each with test true. Nothing is delivered.
  • PATCH /v3/search/subscriptions/{id} changes a subscription. GET reads it and DELETE deletes it.

The answers of GET /v3/callbacks/endpoints and GET /v3/search/subscriptions carry limits: the plan's limit and the number in use (used), for endpoints and for filter and firehose subscriptions.

  • A plan without webhooks gets 403 plan_required.
  • An endpoint or subscription beyond the plan's limit gets 409 limit_reached, with kind.

The limits of each plan are on the fees page.

Endpoint verification

A new endpoint is unverified. So is an endpoint whose url changes, and one that is activated again. SEC Blast sends it an endpoint.verification event, signed like every event. Its data.challenge is 32 hexadecimal characters:

JSON
{
  "type": "endpoint.verification",
  "data": {
    "challenge": "6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6"
  }
}

The endpoint is verified when it answers 2xx within 10 seconds and either:

  • the response body, trimmed of surrounding white space, equals the challenge; or
  • the body is JSON whose challenge field equals it.

A leading UTF-8 byte order mark is ignored. A body that contains the challenge among other text does not verify. Either of these bodies verifies:

Text
6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6

{"challenge": "6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6"}
  • Until the endpoint is verified, its deliveries are held. They are sent once it is verified, and dropped after 72 hours.
  • In the dashboard, you can paste the challenge into the Verify box on the Webhooks page instead. A challenge takes pastes for 24 hours and at most 10 wrong ones; after that, choose Send a new code.

Verify and test

POST /v3/callbacks/endpoints/{id}/verify sends a new challenge and answers 202 with the endpoint.

  • A challenge sent earlier and not yet delivered is dropped. An answer to it no longer verifies.
  • An inactive endpoint gets 409 endpoint_disabled. PATCH with active true verifies it again.

POST /v3/callbacks/endpoints/{id}/test with type sends one sample event of a type the endpoint takes. The event is signed like any event and has test true.

The answer is:

  • 200 with the outcome of the one attempt: delivered, http_status, error_class, and duration_ms.
  • 202 when no attempt was made within 12 seconds. The event is still sent, and the delivery log has the outcome.

A test send is not retried and not billed. It is refused with:

  • 409 test_running while another test of the organization runs;
  • 409 endpoint_unverified or endpoint_disabled.

The two routes share one limit: 6 requests a minute per organization, with a burst of 3. Beyond it they answer 429 rate_limited, with the reason verify_test and Retry-After.

Signatures

Every request is a POST with Content-Type: application/json and the headers of Standard Webhooks:

HeaderValue
webhook-idThe delivery's id, the same on every attempt.
webhook-timestampUnix seconds of this attempt.
webhook-signatureOne or more space-separated v1,<signature> entries.
X-SecBlast-EventThe event type, as the body's type.

The signature is base64(HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<body>")).

  • The key is the bytes that the base64 after whsec_ in the endpoint's secret decodes to.
  • It is computed over the raw request body bytes. A body parsed and serialized again does not verify.
  • While a rotated secret's previous value still signs, the header has two entries. The request is valid when one of them matches.
  • webhook-timestamp is the time of each attempt. A receiver can refuse a request more than 5 minutes from its own clock, as the examples below do.

The body of every event except endpoint.verification has these fields:

FieldMeaning
idThe webhook-id of the delivery.
typeThe event type.
schema_version1. Within a version, changes only add fields.
emitted_atWhen the event was made.
testtrue for a test send.
subscriptionThe subscription that produced the event, {id, name}; null for a test send.
stream_seqFor filing.* events, the event's position in the filing stream.
dataThe event's data, by type (see the table of events).

Python, with Flask:

Python
import base64, hashlib, hmac, json, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["SECBLAST_WEBHOOK_SECRET"]  # the whsec_ value from the endpoint's creation
KEY = base64.b64decode(SECRET.removeprefix("whsec_"))

def verified(body: bytes, headers) -> bool:
    msg_id, ts = headers.get("webhook-id", ""), headers.get("webhook-timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(KEY, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    expected = base64.b64encode(mac).decode()
    entries = headers.get("webhook-signature", "").split()
    return any(e.startswith("v1,") and hmac.compare_digest(e[3:], expected) for e in entries)

@app.post("/secblast")
def secblast_webhook():
    body = request.get_data()  # the raw body bytes, as signed
    if not verified(body, request.headers):
        return "", 400
    event = json.loads(body)
    if event["type"] == "endpoint.verification":
        return event["data"]["challenge"]
    if event["type"] == "filing.new":
        filing = event["data"]["filing"]
        print(event["id"], filing["accession"], filing["form_type"])
    return "", 204

TypeScript, with Express and node:crypto:

TypeScript
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

type Event = { id: string; type: string; data: { challenge?: string; filing?: { accession: string; form_type: string } } };
const secret = process.env.SECBLAST_WEBHOOK_SECRET!; // the whsec_ value from the endpoint's creation
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");

function verified(body: Buffer, h: express.Request["headers"]): boolean {
  const id = String(h["webhook-id"] ?? ""), ts = String(h["webhook-timestamp"] ?? "");
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = createHmac("sha256", key).update(`${id}.${ts}.`).update(body).digest();
  return String(h["webhook-signature"] ?? "").split(" ").some((e) => {
    const sig = e.startsWith("v1,") ? Buffer.from(e.slice(3), "base64") : Buffer.alloc(0);
    return sig.length === expected.length && timingSafeEqual(sig, expected);
  });
}

const app = express();
// express.raw keeps the body as the bytes that were signed.
app.post("/secblast", express.raw({ type: "application/json" }), (req, res) => {
  if (!verified(req.body, req.headers)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8")) as Event;
  if (event.type === "endpoint.verification") return res.type("text/plain").send(event.data.challenge);
  if (event.type === "filing.new") console.log(event.id, event.data.filing?.accession, event.data.filing?.form_type);
  return res.sendStatus(204);
});

Retries

  • An attempt fails when the endpoint does not answer 2xx within 10 seconds. Redirects are not followed.
  • A delivery is attempted up to 12 times in total, over about 71 hours, and is then failed.
  • A 410 answer fails the delivery at once and disables the endpoint.
  • Delivery is at least once: every attempt of a delivery carries the same webhook-id, which is also the body's id. Use it to drop duplicates.
  • A delivery is billed when your endpoint answers 2xx: its payload size counts toward the plan's monthly data transfer. Failed attempts, test sends, and verifications are not billed.

Endpoint health

Each endpoint has health.state, and last_24h: its deliveries of the last 24 hours by state.

StateMeaning
unverifiedWaiting for the answer to its challenge. Deliveries are held.
activeVerified. Deliveries are sent.
failingA delivery failed every attempt within one hour, or 10 attempts in a row failed. Deliveries are still sent. One success makes the endpoint active again.
disabledEvery attempt failed for 72 hours, with at least 20 attempts, or the endpoint answered 410. New deliveries are held for 72 hours, then dropped. PATCH with active true makes the endpoint unverified and sends a challenge. Once it is verified, the held deliveries are sent in order.

An endpoint set to active false holds nothing: its deliveries are dropped.

Delivery log, retry, and replay

GET /v3/callbacks/deliveries lists the organization's deliveries, newest first. Each has attempt_count, last_status, last_error, and, while an attempt is due, next_attempt_at. GET /v3/callbacks/deliveries/{id} adds the payload and every attempt.

The list filters by:

  • endpoint_id or subscription_id;
  • state or type;
  • accession, for one filing;
  • from and to, on created_at.

Deliveries are kept 30 days after their final state. The list pages with cursor and next_cursor (Pagination). A cursor is opaque: send it back as you received it.

StateMeaning
pendingWaiting for its next attempt.
heldWaiting for a condition, named in held_reason: an unverified or disabled endpoint, the plan, the monthly transfer, or a digest interval.
deliveringAn attempt is in flight.
deliveredThe endpoint answered 2xx.
failedEvery attempt failed, or a hold ran out; last_error says which.
droppedThe endpoint was inactive, or a hold on an unverified or disabled endpoint ran out.

POST /v3/callbacks/deliveries/{id}/retry queues one more attempt of a failed delivery now and answers 202.

  • The attempt count goes on from where it was.
  • A delivery can be retried this way twice. After that it gets 409 limit_reached.
  • Only a failed delivery that was never billed can be retried. Any other gets 409 invalid_state.

POST /v3/callbacks/endpoints/{id}/replay queues again the failed and dropped deliveries of one endpoint, oldest first. It takes from, and optionally to, states, and types.

  • Only deliveries created in that window are queued. The window is at most 30 days.
  • One call queues at most 10,000 deliveries.
  • Billed deliveries, test sends, and verifications are never queued again.
  • A replay of the same endpoint within 60 seconds of the last gets 409 replay_running with Retry-After.

The answer is 202 with {replayed, truncated, last_created_at}. When truncated is true, call again with the same to, states, and types, and with from set to last_created_at.

JSON
{
  "replayed": 214,
  "truncated": false,
  "last_created_at": null
}

Markdown version: /docs/webhooks/reference.md