Reference

Webhook events

Seven events, plus a test event from the test button.

On this page

Every event has the envelope described in Developer webhooks. These are the data fields of each, with the whole body of a sample delivery. The values are made up; the shapes are checked against the engine.

Event	Raised when
`job.done`	An article job finished and its credits were captured. Raised for article jobs only.
`job.failed`	An article job failed, or was cancelled, and the credits it held were released.
`article.approved`	A person approved a version, or pressed republish on a version that is already approved. Not raised when an edit takes the approval away. A language version is an article of its own: approving it raises its own event, and approving the article it belongs to does not approve it.
`article.exported`	An export was rendered, or an article was delivered to a connection.
`beat.run.done`	A Beat run finished. Raised for runs that finished, not for failed ones.
`agent.budget_exhausted`	A key or an agent used its daily cap. At most once per credential per UTC day.
`site.read`	A read of a site finished, whether it succeeded or failed.
`test`	Send a test, in Developer › Webhooks. Not an event you can subscribe to.

job.done#

An article job finished and its credits were captured. Raised for article jobs only.

Field in `data`	Meaning
`jobId`	Lower-case UUID of the job.
`articleId`	Lower-case UUID of the article the job wrote. For a job that adds language versions, the article they were added to; the versions are listed in its `languageVersions`.
`credits`	Credits captured for the run. The credits of language versions that were skipped, failed or came back empty are not in it.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "articleId": "9f3b1c2a-6d4e-4b7a-8c15-2e0a7d91b3f4",
    "credits": 1,
    "jobId": "c8a41e07-52b9-4d36-8f1a-0b7e9d3c6a25"
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "job.done",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a job.done delivery

job.failed#

An article job failed, or was cancelled, and the credits it held were released.

Field in `data`	Meaning
`jobId`	Lower-case UUID of the job.
`articleId`	The article the job was writing.
`failure`	The first sentence of the last failure, lower-cased, or `cancelled` when the job was cancelled.
`refunded`	Credits released back to the workspace, as a number.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "articleId": "9f3b1c2a-6d4e-4b7a-8c15-2e0a7d91b3f4",
    "failure": "the model provider did not answer",
    "jobId": "c8a41e07-52b9-4d36-8f1a-0b7e9d3c6a25",
    "refunded": 1
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "job.failed",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a job.failed delivery

article.approved#

A person approved a version, or pressed republish on a version that is already approved. Not raised when an edit takes the approval away. A language version is an article of its own: approving it raises its own event, and approving the article it belongs to does not approve it.

Field in `data`	Meaning
`article`	The article as `GET /articles/{id}` returns it for a key, without `comments`. Ids inside it are upper-case.
`version`	The approved version.
`approvedBy`	Name of the person who approved.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "approvedBy": "Maya Chen",
    "article": {
      "blocks": [
        {
          "claimIds": [
            "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
          ],
          "n": 1,
          "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said."
        },
        {
          "claimIds": [],
          "kind": "heading",
          "level": 2,
          "n": 2,
          "text": "What changes for commuters"
        },
        {
          "claimIds": [
            "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
            "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
          ],
          "n": 3,
          "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them."
        }
      ],
      "brandName": "Kolibri Courier",
      "by": "Maya Chen · via agent",
      "claims": [
        {
          "id": "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045",
          "keptFlag": false,
          "originCount": 2,
          "paragraph": 1,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
            "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
          ],
          "state": "corroborated",
          "text": "The shared timetable starts on 3 November."
        },
        {
          "id": "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
          "keptFlag": false,
          "originCount": 1,
          "paragraph": 3,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4"
          ],
          "state": "singleSource",
          "text": "The route will have 14 daily crossings instead of 9."
        },
        {
          "id": "A63F2E58-9C10-47DB-8E3A-D5B07C41F192",
          "keptFlag": false,
          "originCount": 2,
          "paragraph": 3,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
            "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
          ],
          "state": "corroborated",
          "text": "A single fare table applies on all crossings."
        }
      ],
      "deck": "The harbour authority says commuters get 14 daily crossings.",
      "id": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4",
      "label": {
        "approvedAt": "2026-10-06T12:31:40Z",
        "approvedBy": "Maya Chen",
        "approvedVersion": 1,
        "reviewedByHuman": true
      },
      "language": "en",
      "lead": "Three ferry operators will publish one shared timetable for the northern route from 3 November.",
      "origin": "agent",
      "paragraphs": [
        {
          "claimIds": [
            "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
          ],
          "n": 1,
          "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said."
        },
        {
          "claimIds": [],
          "n": 2,
          "text": "## What changes for commuters"
        },
        {
          "claimIds": [
            "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
            "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
          ],
          "n": 3,
          "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them."
        }
      ],
      "quality": [
        {
          "detail": "Every figure and quote in the text appears in a source.",
          "id": "q-readback",
          "name": "Read back against the sources",
          "verdict": "passed"
        },
        {
          "detail": "412 words.",
          "id": "q-length",
          "name": "Length",
          "verdict": "warning"
        }
      ],
      "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
      "sources": [
        {
          "contributed": "Contributed: 2 claims",
          "id": "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
          "official": false,
          "origin": "harbour-authority.example",
          "score": 75,
          "soleForClaims": 1,
          "title": "Northern route: one timetable from 3 November",
          "url": "https://harbour-authority.example/news/northern-route-timetable"
        },
        {
          "contributed": "Contributed: 2 claims",
          "id": "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982",
          "official": false,
          "origin": "coast-gazette.example",
          "score": 75,
          "soleForClaims": 0,
          "title": "Ferries to share a timetable",
          "url": "https://coast-gazette.example/transport/ferries-share-timetable"
        }
      ],
      "status": "approved",
      "title": "Ferry operators agree on a single timetable for the northern route",
      "versions": [
        {
          "agent": "Claude (newsroom agent)",
          "by": "Claude (newsroom agent)",
          "label": "Generated",
          "model": "writer-v3",
          "n": 1,
          "note": "Written from 2 origins · 3 claims checked · 1 marked",
          "when": "2026-10-06T12:04:11Z"
        }
      ],
      "words": 412
    },
    "version": 1
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "article.approved",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a article.approved delivery

article.exported#

An export was rendered, or an article was delivered to a connection.

Field in `data`	Meaning
`article`	The article as it was when exported, without `comments`.
`version`	The exported version.
`target`	`markdown`, `pdf`, `docx`, or `delivered to <connection name>`.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "article": {
      "blocks": [
        {
          "claimIds": [
            "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
          ],
          "n": 1,
          "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said."
        },
        {
          "claimIds": [],
          "kind": "heading",
          "level": 2,
          "n": 2,
          "text": "What changes for commuters"
        },
        {
          "claimIds": [
            "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
            "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
          ],
          "n": 3,
          "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them."
        }
      ],
      "brandName": "Kolibri Courier",
      "by": "Maya Chen · via agent",
      "claims": [
        {
          "id": "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045",
          "keptFlag": false,
          "originCount": 2,
          "paragraph": 1,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
            "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
          ],
          "state": "corroborated",
          "text": "The shared timetable starts on 3 November."
        },
        {
          "id": "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
          "keptFlag": false,
          "originCount": 1,
          "paragraph": 3,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4"
          ],
          "state": "singleSource",
          "text": "The route will have 14 daily crossings instead of 9."
        },
        {
          "id": "A63F2E58-9C10-47DB-8E3A-D5B07C41F192",
          "keptFlag": false,
          "originCount": 2,
          "paragraph": 3,
          "sourceIds": [
            "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
            "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
          ],
          "state": "corroborated",
          "text": "A single fare table applies on all crossings."
        }
      ],
      "deck": "The harbour authority says commuters get 14 daily crossings.",
      "id": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4",
      "label": {
        "approvedAt": "2026-10-06T12:31:40Z",
        "approvedBy": "Maya Chen",
        "approvedVersion": 1,
        "reviewedByHuman": true
      },
      "language": "en",
      "lead": "Three ferry operators will publish one shared timetable for the northern route from 3 November.",
      "origin": "agent",
      "paragraphs": [
        {
          "claimIds": [
            "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
          ],
          "n": 1,
          "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said."
        },
        {
          "claimIds": [],
          "n": 2,
          "text": "## What changes for commuters"
        },
        {
          "claimIds": [
            "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
            "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
          ],
          "n": 3,
          "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them."
        }
      ],
      "quality": [
        {
          "detail": "Every figure and quote in the text appears in a source.",
          "id": "q-readback",
          "name": "Read back against the sources",
          "verdict": "passed"
        },
        {
          "detail": "412 words.",
          "id": "q-length",
          "name": "Length",
          "verdict": "warning"
        }
      ],
      "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
      "sources": [
        {
          "contributed": "Contributed: 2 claims",
          "id": "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
          "official": false,
          "origin": "harbour-authority.example",
          "score": 75,
          "soleForClaims": 1,
          "title": "Northern route: one timetable from 3 November",
          "url": "https://harbour-authority.example/news/northern-route-timetable"
        },
        {
          "contributed": "Contributed: 2 claims",
          "id": "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982",
          "official": false,
          "origin": "coast-gazette.example",
          "score": 75,
          "soleForClaims": 0,
          "title": "Ferries to share a timetable",
          "url": "https://coast-gazette.example/transport/ferries-share-timetable"
        }
      ],
      "status": "approved",
      "title": "Ferry operators agree on a single timetable for the northern route",
      "versions": [
        {
          "agent": "Claude (newsroom agent)",
          "by": "Claude (newsroom agent)",
          "label": "Generated",
          "model": "writer-v3",
          "n": 1,
          "note": "Written from 2 origins · 3 claims checked · 1 marked",
          "when": "2026-10-06T12:04:11Z"
        }
      ],
      "words": 412
    },
    "target": "markdown",
    "version": 1
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "article.exported",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a article.exported delivery

beat.run.done#

A Beat run finished. Raised for runs that finished, not for failed ones.

Field in `data`	Meaning
`beatId`	Lower-case UUID of the Beat.
`candidates`	Candidates the run found.
`written`	Articles it wrote.
`credits`	Credits it spent.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "beatId": "2d7c9e41-5a08-4b36-8c1f-e3a60b9d7f52",
    "candidates": 6,
    "credits": 2,
    "written": 2
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "beat.run.done",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a beat.run.done delivery

agent.budget_exhausted#

A key or an agent used its daily cap. At most once per credential per UTC day.

Field in `data`	Meaning
`keyId`	Lower-case UUID of the key or agent.
`name`	Its name.
`kind`	`key` or `agent`.
`cap`	Its daily cap in credits.
`resetsAt`	When the cap resets: the next 00:00 UTC.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "cap": 5,
    "keyId": "6c1d9f3e-8a25-4b70-93e4-d7a0b5c28f19",
    "kind": "agent",
    "name": "Claude (newsroom agent)",
    "resetsAt": "2026-10-07T00:00:00Z"
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "agent.budget_exhausted",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a agent.budget_exhausted delivery

site.read#

A read of a site finished, whether it succeeded or failed.

Field in `data`	Meaning
`siteId`	Lower-case UUID of the site.
`domain`	Its domain.
`status`	`ready` or `failed`.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "domain": "kolibri.example",
    "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
    "status": "ready"
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "site.read",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a site.read delivery

test#

Send a test, in Developer › Webhooks. Not an event you can subscribe to.

Field in `data`	Meaning
`test`	Always `true`. Sent by Send a test in Developer › Webhooks.

JSON

{
  "createdAt": "2026-10-06T12:31:41Z",
  "data": {
    "test": true
  },
  "id": "evt_5f7b6a64-1c1e-4a0b-9d2a-3c8a8e0f1a11",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "type": "test",
  "workspaceId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

Body of a test delivery