> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Monitors webhook payload

> The body and headers of every Monitors webhook delivery: the event envelope, the nine event types, and the monitor, run and result objects in data.

Every Monitors webhook delivery is an HTTP `POST` with a JSON body: one event in a fixed envelope, signed with the monitor's `webhook.secret`. This page lists the headers, the envelope fields, each event type and the objects in `data`, so your handler can parse every event it subscribes to. To set up a handler and verify signatures, see [Receive monitor webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md).

## Headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `webhook-id` | The event's `id`, such as `evt_9f2c4e1a7b3d4c5e8f6a0b1c2d3e4f5a`. The same on every retry |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds |
| `webhook-signature` | `v1,<signature>`: base64 of HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>`, keyed with the base64-decoded part of `webhook.secret` after `whsec_`. Space-separated if there is more than one entry |

A delivery can carry other headers. Verify it with these three, as [Verify the signature](https://docs.keenable.ai/guides/monitor-webhooks.md#verify-the-signature) shows.

## Envelope

Every event has the same five top-level fields:

| Field | Type | What it holds |
| - | - | - |
| `id` | string | The event's ID, `evt_` and 32 hex characters. Equal to `webhook-id`. Drop repeats by it |
| `type` | string | One of the [event types](#event-types) |
| `created_at` | string | When the event was created, ISO 8601 in UTC with milliseconds, such as `2026-11-19T09:00:03.512Z`. It stays the same across retries |
| `data` | object | `monitor_id` plus one object that depends on `type` |
| `metadata` | object or `null` | The `metadata` you set on the monitor, or `null` if it has none |

## Event types

A monitor sends only the types its `webhook.events` lists. If `webhook.events` is empty or missing, it sends every type in this table.

| `type` | `data` holds | Sent when |
| - | - | - |
| `monitor.created` | `monitor_id`, `monitor` | You created the monitor |
| `monitor.updated` | `monitor_id`, `monitor` | You changed the monitor |
| `monitor.deleted` | `monitor_id`, `monitor` | You deleted the monitor |
| `monitor.run.created` | `monitor_id`, `run` | A scheduled or triggered run started |
| `monitor.run.completed` | `monitor_id`, `run` | A run finished. A run with no new results still sends it, with `results: []` |
| `monitor.run.failed` | `monitor_id`, `run` | A run failed. `run.error.message` says why |
| `monitor.disabled` | `monitor_id`, `monitor`, `reason` | Keenable disabled the monitor. `reason` is a sentence, such as `no webhook delivery succeeded for 3 days` |
| `monitor.result.found` | `monitor_id`, `result` | The monitor accepted a new page, minutes after Keenable crawled it |
| `monitor.result.changed` | `monitor_id`, `result` with `change` | A page you already got changed in substance |

## Objects in data

### monitor

`monitor` is the monitor as [Get a monitor](https://docs.keenable.ai/api-reference/monitors/get.md) returns it, with its state after the change. It never carries `webhook.secret`.

### run

`run` is a run as [Get a run](https://docs.keenable.ai/api-reference/monitors/run.md) returns it:

| Field | What it holds |
| - | - |
| `id`, `monitor_id` | The run's ID and its monitor's ID |
| `object` | Always `monitor_run` |
| `status` | `queued`, `running`, `completed`, `failed` or `cancelled` |
| `results` | A list of [result](#result) objects when `status` is `completed`, `[]` if the run found nothing new, otherwise `null` |
| `output` | `{structured, text, grounding}` if the monitor has an `output_schema` and the run found results, otherwise `null` |
| `error` | `{"code": "run_failed", "message": "..."}` on a failed run, otherwise `null` |
| `created_at`, `started_at`, `ended_at` | When the run was created, started and ended, or `null` |
| `changes` | Always `null` for now |

### result

`result` in `monitor.result.found` and `monitor.result.changed` has the fields of a result from [List results](https://docs.keenable.ai/api-reference/monitors/results.md), except `id` and `same_story`:

| Field | What it holds |
| - | - |
| `url`, `title` | The page's URL and title |
| `published_at`, `published_at_source` | When the page was published, and where that date comes from: `declared`, `url`, `x` or `text` |
| `acquired_at` | When Keenable crawled this version of the page |
| `matched_at` | When the monitor accepted the page |
| `summary` | One line on what the page reports |
| `importance` | How much the page matters for the monitor's topic, from 1 to 5. A monitor accepts no page under 3 |
| `kind` | A label for the kind of page, such as `news` or `new_item` |
| `source_type` | `original` or `rewrite` |
| `text` | The page's first 6,000 characters. Present only if the monitor sets `search.content.text` |
| `change` | Present only in `monitor.result.changed`. See [change](#change) |
| `author`, `image` | Always `null` in webhook events |

### change

`change` says how a page differs from the version the monitor stored before:

| Field | What it holds |
| - | - |
| `previous_at` | When the earlier version was stored |
| `previous_title` | The earlier version's title |
| `previous_sent` | Whether the earlier version was sent to you |
| `ratio` | How much of the text is new, from 0 to 1 |
| `added`, `removed` | The sentences added and removed |

## Example bodies

A `monitor.result.found` event, formatted here for reading. Keenable sends the body as compact JSON, so verify the bytes you received, not a reformatted copy:

```json monitor.result.found theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "id": "evt_9f2c4e1a7b3d4c5e8f6a0b1c2d3e4f5a",
  "type": "monitor.result.found",
  "created_at": "2026-11-19T09:00:03.512Z",
  "data": {
    "monitor_id": "mon_3kq9z2c8f1a04b7d9e6f5a21",
    "result": {
      "url": "https://example.com/news/example-70b",
      "title": "Example Labs releases a 70B open-weights model",
      "author": null,
      "published_at": "2026-11-19T08:41:00.000Z",
      "acquired_at": "2026-11-19T08:52:17.000Z",
      "image": null,
      "matched_at": "2026-11-19T08:59:58.000Z",
      "published_at_source": "declared",
      "summary": "Example Labs released a 70B model with open weights under a permissive licence.",
      "importance": 4,
      "kind": "news",
      "source_type": "original"
    }
  },
  "metadata": { "team": "research" }
}
```

A `monitor.run.completed` event for a run that found nothing new:

```json monitor.run.completed theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "id": "evt_0b7d2e94c1f84a6b9d3e5f7a8c1b2d4e",
  "type": "monitor.run.completed",
  "created_at": "2026-11-19T08:00:41.207Z",
  "data": {
    "monitor_id": "mon_3kq9z2c8f1a04b7d9e6f5a21",
    "run": {
      "id": "mrun_5c1e8a2f9d7b4e3a6f0c2d81",
      "object": "monitor_run",
      "monitor_id": "mon_3kq9z2c8f1a04b7d9e6f5a21",
      "status": "completed",
      "results": [],
      "changes": null,
      "output": null,
      "error": null,
      "created_at": "2026-11-19T08:00:00.004Z",
      "started_at": "2026-11-19T08:00:00.120Z",
      "ended_at": "2026-11-19T08:00:41.198Z"
    }
  },
  "metadata": null
}
```

Values in these examples are illustrative. Field names and types match what the API sends.

## Types for your handler

If your SDK version doesn't have typed webhook events yet, these TypeScript types describe the envelope and the objects above. Use them after you verify the signature:

```typescript keenable-webhook.ts theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
export type MonitorEventType =
  | "monitor.created" | "monitor.updated" | "monitor.deleted"
  | "monitor.run.created" | "monitor.run.completed" | "monitor.run.failed"
  | "monitor.disabled" | "monitor.result.found" | "monitor.result.changed";

export interface MonitorResultChange {
  previous_at: string | null;
  previous_title: string | null;
  previous_sent: boolean | null;
  ratio: number | null;
  added: string[] | null;
  removed: string[] | null;
}

export interface MonitorResult {
  url: string;
  title: string | null;
  author: null;
  published_at: string | null;
  published_at_source: string | null;
  acquired_at: string | null;
  matched_at: string | null;
  image: null;
  summary: string | null;
  importance: number | null;
  kind: string | null;
  source_type: string | null;
  text?: string;
  change?: MonitorResultChange;
}

export interface MonitorRun {
  id: string;
  object: "monitor_run";
  monitor_id: string;
  status: "queued" | "running" | "completed" | "failed" | "cancelled";
  results: MonitorResult[] | null;
  output: { structured: unknown; text: string | null; grounding: unknown[] } | null;
  error: { code: string; message: string } | null;
  created_at: string | null;
  started_at: string | null;
  ended_at: string | null;
}

export interface MonitorWebhookEvent {
  id: string;
  type: MonitorEventType;
  created_at: string;
  data: {
    monitor_id: string;
    monitor?: Record<string, unknown>;
    run?: MonitorRun;
    result?: MonitorResult;
    reason?: string;
  };
  metadata: Record<string, string> | null;
}
```

Switch on `type` to read the right field of `data`. For example, `event.type === "monitor.result.found"` means `event.data.result` is set. SDK 0.2.0 and later return these events typed from `verify_webhook` (`verifyWebhook` in TypeScript, `VerifyWebhook` in Go).

## Related pages

* [Receive monitor webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md): subscribe, verify, test locally and debug deliveries.
* [List deliveries](https://docs.keenable.ai/api-reference/monitors/deliveries.md): each event's attempts and last error.
* [Monitors](https://docs.keenable.ai/products/monitors#webhook-events): retries, statuses and limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.