# 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](https://www.secblast.com/docs/webhooks).

## Endpoints

[`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-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.

- [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) lists the endpoints, each with its health and its deliveries of the last 24 hours.
- [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) changes `url`, `description`, `event_types`, or `active`. `DELETE` deletes the endpoint and deactivates the subscriptions that deliver to it.
- [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) issues a new secret, shown once. The previous secret keeps signing beside it for `expire_previous_in_s` seconds.

`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`](https://www.secblast.com/docs/reference/post-search-subscriptions) creates a subscription. It takes `name`, `query`, and `endpoint_id`. `query` is a JSON object with the filters of [`GET /v3/search`](https://www.secblast.com/docs/reference/get-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`](https://www.secblast.com/docs/reference/post-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}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) changes a subscription. `GET` reads it and `DELETE` deletes it.

The answers of [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) and [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-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](https://www.secblast.com/pricing).

## 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`](https://www.secblast.com/docs/reference/post-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`](https://www.secblast.com/docs/reference/post-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:

| 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-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:

| 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:

```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.

| 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`](https://www.secblast.com/docs/reference/get-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}`](https://www.secblast.com/docs/reference/get-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](https://www.secblast.com/docs/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`](https://www.secblast.com/docs/reference/post-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`](https://www.secblast.com/docs/reference/post-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
}
```
