# Earnings monitoring

**What you build:** a webhook handler that runs when a company files an earnings release. It reads the quarter, the income statement, and the same figure for peers.

**The result:** for Getty Images' third quarter of 2026, revenue of $234.0 million against $240.0 million a year earlier, diluted EPS of -$1.34 against $0.05, and the same quarter's revenue of Shutterstock, Yelp, and Ziff Davis.

**Plan:** webhooks are part of the Builder, Business, and Enterprise plans. On any plan, the [stream](https://www.secblast.com/docs/stream) carries the same new filings: pass each 8-K it sends to `on_filing` in the script.

## Get each earnings release

**1. Subscribe.** A subscription on 8-K filings with Item 2.02 (results of operations, the item of an earnings release) sends each new one to your webhook endpoint. Create the endpoint first ([Webhooks](https://www.secblast.com/docs/webhooks)).

```python
import os
import requests

r = requests.post(
    "https://api.secblast.com/v3/search/subscriptions",
    json={
        "name": "8-K filings with Item 2.02",
        "endpoint_id": "cbe_0123456789abcdef01234567",
        "query": {
            "forms": "8-K",
            "items": [
                "2.02"
            ]
        }
    },
    headers={"Authorization": f"Bearer {os.environ['SECBLAST_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())
```

```json
{
  "id": "sub_0123456789abcdef01234567",
  "name": "8-K filings with Item 2.02",
  "kind": "filing",
  "endpoint_id": "cbe_0123456789abcdef01234567",
  "include_corrections": false,
  "min_interval_s": null,
  "active": true,
  "created_at": "2026-11-16T15:00:00Z"
}
```

**2. Receive the filing.** Each matching filing arrives as a signed `filing.new` delivery, shown here with the fields the script reads ([Webhooks](https://www.secblast.com/docs/webhooks) has the whole envelope). The handler takes the company's CIK from `data.filing.entities`.

```http
POST <your endpoint>
Content-Type: application/json
webhook-id: str_000000000184467
webhook-timestamp: 1763333700
webhook-signature: v1,<signature>
X-SecBlast-Event: filing.new

{
  "id": "str_000000000184467",
  "type": "filing.new",
  "data": {
    "filing": {
      "accession": "0001628280-26-074189",
      "form_type": "8-K",
      "filing_date": "2026-11-16",
      "items": ["2.02","9.01"],
      "entities": [{"cik":"0001898496","name":"Getty Images Holdings, Inc.","role":"filer"}]
    }
  }
}
```

## The script

Your webhook handler calls `on_filing` with each delivery. It does steps 3 to 5.

```python
import os
import requests

API = "https://api.secblast.com"
KEY = os.environ["SECBLAST_API_KEY"]

def get(path, **params):
    r = requests.get(API + path, params=params, headers={"Authorization": f"Bearer {KEY}"}, timeout=30)
    r.raise_for_status()
    return r

# Peers by CIK, the company itself included.
PEERS = {"0001898496": "Getty Images", "0001549346": "Shutterstock", "0001345016": "Yelp", "0001084048": "Ziff Davis"}

def on_filing(delivery):
    """Steps 3 to 5, for one filing.new delivery."""
    filing = delivery["data"]["filing"]
    cik = int(filing["entities"][0]["cik"])

    # 3. Read the earnings event: the quarter, and the exhibit with the release.
    events = get("/v3/events/8k/2.02", cik=cik, filed_from=filing["filing_date"], filed_to=filing["filing_date"]).json()["data"]
    if not events:
        return  # not an earnings release
    fields = {f["name"]: f["value"] for f in events[0]["events"][0]["fields"]}

    # 4. Get the income statement: this quarter and the same quarter a year earlier.
    statement = get(f"/v3/companies/{cik}/statements", kind="IS", limit=1).json()["data"][0]["statements"][0]
    period = statement["columns"][0]["period"]
    if period["end"] != fields["period_end"]:
        return  # the 10-Q for this quarter is not filed yet
    for row in statement["rows"]:
        print(row["label"], [c["value"] for c in row["cells"]])

    # 5. Compare peers: the same revenue concept for the same quarter, across every filer.
    concept = statement["rows"][0]["concept"]
    frame = get("/v3/financials/frames", concept=concept, period=f"{period['start']}/{period['end']}",
                unit="iso4217:USD", limit=50000).json()["data"]
    for row in frame:
        if row["entity_cik"] in PEERS:
            print(PEERS[row["entity_cik"]], row["value"])

```

## What each step returns

**3. Read the earnings event.** The Item 2.02 event of that company and day gives the quarter (`period_end`) and the exhibit that holds the release. A filing without the event is not an earnings release, and the script stops.

```json
{
  "data": [
    {
      "filing": {
        "accession": "0001628280-26-074189",
        "form_type": "8-K",
        "filing_date": "2026-11-16",
        "primary_name": "Getty Images Holdings, Inc."
      },
      "item_code": "2.02",
      "events": [
        {
          "event_type": "earnings_release",
          "confidence": 0.9,
          "exhibits": [
            {
              "doc_seq": 2,
              "number": "99.1",
              "type": "EX-99.1",
              "url": "/v3/filings/0001628280-26-074189/documents/2"
            }
          ],
          "fields": [
            {"name":"period_end","value":"2026-09-30","confidence":0.9},
            {"name":"period_kind","value":"q3","confidence":0.9},
            {"name":"release_date","value":"2026-11-16","confidence":0.9}
          ]
        }
      ]
    }
  ]
}
```

**4. Get the income statement.** The latest income statement has the quarter and the same quarter a year earlier as columns, so revenue and EPS compare directly. When its quarter is not `period_end`, the 10-Q is not filed yet and the script stops.

```json
{
  "cik": "0001898496",
  "data": [
    {
      "accession": "0001628280-26-074191",
      "filing": {"form_type":"10-Q","filing_date":"2026-11-16","period_of_report":"2026-09-30"},
      "statements": [
        {
          "columns": [
            {"period":{"start":"2026-07-01","end":"2026-09-30"}},
            {"period":{"start":"2025-07-01","end":"2025-09-30"}}
          ],
          "rows": [
            {
              "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
              "label": "Revenue",
              "cells": [{"value":"234029000"},{"value":"240044000"}]
            },
            {
              "concept": "us-gaap:EarningsPerShareDiluted",
              "label": "Diluted (in dollars per share)",
              "cells": [{"value":"-1.34"},{"value":"0.05"}]
            }
          ]
        }
      ]
    }
  ]
}
```

**5. Compare peers.** A frame returns one concept for one period across every filer. The concept and the period come from step 4. A frame has no company filter, so the script picks peers by CIK: `0001898496` is Getty Images, `0001549346` Shutterstock, `0001345016` Yelp, and `0001084048` Ziff Davis. One page can hold every filer's value for the quarter, and it counts toward your data transfer.

```json
{
  "data": [
    {"entity_cik":"0001898496","value":"234029000","unit_norm":"iso4217:USD"},
    {"entity_cik":"0001549346","value":"173898000","unit_norm":"iso4217:USD"},
    {"entity_cik":"0001345016","value":"370919000","unit_norm":"iso4217:USD"},
    {"entity_cik":"0001084048","value":"289326000","unit_norm":"iso4217:USD"}
  ]
}
```
