Webhooks reference
On this page
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
.localor.internal.
Source address: deliveries come from 67.227.64.202, over IPv4.
GET /v3/callbacks/endpointslists the endpoints, each with its health and its deliveries of the last 24 hours.PATCH /v3/callbacks/endpoints/{id}changesurl,description,event_types, oractive.DELETEdeletes the endpoint and deactivates the subscriptions that deliver to it.POST /v3/callbacks/endpoints/{id}/rotate-secretissues a new secret, shown once. The previous secret keeps signing beside it forexpire_previous_in_sseconds.
event_types lists the events the endpoint receives:
| Event | When |
|---|---|
filing.new | A new filing matches a subscription. data.filing is the filing. |
filing.updated | A 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.corrected | SEC corrects a filing already sent. data.changes lists the header fields and documents that changed. Sent to subscriptions with include_corrections. |
filing.digest | The filing.new events of a subscription with min_interval_s, gathered over its interval: data.events, data.count, and data.truncated. |
endpoint.verification | The 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:
formsorform_families: a form type with its variants, such as10-K, which also matches10-K/A.form_types: the exact form type, such as10-K/A.ciksandtickers: companies. Tickers are resolved to CIKs when the subscription is saved.sics: SIC industry codes.statesandinc_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_correctionstruealso sendsfiling.updatedandfiling.correctedfor the filings the subscription has sent.min_interval_ssends at most one request per interval. The events of the interval arrive together as onefiling.digest.- A subscription receives new filings, so a filing-date window (
filed_from,filed_to) orstatusin the query gets400, naming it. - A subscription matches filings by their filing-level fields, so
q,doctypes,primary_only=true, orentityNamein the query gets400invalid_parameter, naming that parameter. POST /v3/search/subscriptions/{id}/testanswers with the events the subscription would have sent for recent filings, each withtesttrue. Nothing is delivered.PATCH /v3/search/subscriptions/{id}changes a subscription.GETreads it andDELETEdeletes 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
403plan_required. - An endpoint or subscription beyond the plan's limit gets
409limit_reached, withkind.
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:
{
"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
challengefield 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:
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
409endpoint_disabled.PATCHwithactivetrueverifies 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:
200with the outcome of the one attempt:delivered,http_status,error_class, andduration_ms.202when 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:
409test_runningwhile another test of the organization runs;409endpoint_unverifiedorendpoint_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:
| Header | Value |
|---|---|
webhook-id | The delivery's id, the same on every attempt. |
webhook-timestamp | Unix seconds of this attempt. |
webhook-signature | One or more space-separated v1,<signature> entries. |
X-SecBlast-Event | The 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-timestampis 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:
| Field | Meaning |
|---|---|
id | The webhook-id of the delivery. |
type | The event type. |
schema_version | 1. Within a version, changes only add fields. |
emitted_at | When the event was made. |
test | true for a test send. |
subscription | The subscription that produced the event, {id, name}; null for a test send. |
stream_seq | For filing.* events, the event's position in the filing stream. |
data | The event's data, by type (see the table of events). |
Python, with Flask:
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 "", 204TypeScript, with Express and node:crypto:
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
2xxwithin 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
410answer 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'sid. 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.
| State | Meaning |
|---|---|
unverified | Waiting for the answer to its challenge. Deliveries are held. |
active | Verified. Deliveries are sent. |
failing | A 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. |
disabled | Every 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_idorsubscription_id;stateortype;accession, for one filing;fromandto, oncreated_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.
| State | Meaning |
|---|---|
pending | Waiting for its next attempt. |
held | Waiting for a condition, named in held_reason: an unverified or disabled endpoint, the plan, the monthly transfer, or a digest interval. |
delivering | An attempt is in flight. |
delivered | The endpoint answered 2xx. |
failed | Every attempt failed, or a hold ran out; last_error says which. |
dropped | The 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
409limit_reached. - Only a failed delivery that was never billed can be retried. Any other gets
409invalid_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
409replay_runningwithRetry-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.
{
"replayed": 214,
"truncated": false,
"last_created_at": null
}Markdown version: /docs/webhooks/reference.md