Webhook events and delivery

Receive signed JSON notifications, then use authenticated event feeds as the durable source. Delivery must be active in the selected hosted environment. Configure endpoints through create_webhook.

Request headers and verification

Header	Meaning
Content-Type	application/json
User-Agent	LinktrailWebhook/1 (unchanged until the DP-0029-T05 cutover)
AgentLinkOps-Timestamp	Unix seconds as a string
AgentLinkOps-Signature	One or two space-separated v1=HEX signatures
AgentLinkOps-Delivery-Id	Stable whd_ delivery identifier across retries
AgentLinkOps-Event-Type	Event type; empty for digests

Every delivery also carries Linktrail-Timestamp, Linktrail-Signature, Linktrail-Delivery-Id and Linktrail-Event-Type with identical values. That compatibility set exists for receivers written against the working name; read either set, and move to the AgentLinkOps names before the dated cutover release removes the old ones (DP-0029-T05, after pilot customers are notified). The signing procedure is the same for both. Compute HMAC-SHA-256 using the full whsec_ secret over the timestamp, a literal dot, and the exact raw UTF-8 body. Compare hex signatures in constant time. Reject invalid timestamps or timestamps more than 300 seconds away from the receiver clock. During rotation, accept a match against either active secret and any offered signature. Persist the raw notification or enqueue it durably before answering 2xx. Deduplicate work by AgentLinkOps-Delivery-Id in durable storage. Do not mark a delivery processed before its work has been durably accepted. The event ID supplies a separate identity when reconciling with pulled feed records.

Per-event payload

{
  "v": 1,
  "feed": "events",
  "type": "placement_acquired",
  "id": "evt_example",
  "sequence": 42,
  "workspace_id": "ws_example",
  "project_id": "prj_example",
  "subject_id": "watch_example",
  "created_at": "2026-09-13T12:00:00.000Z",
  "transition": "present",
  "previous": null,
  "uncertain": false,
  "checked_at": "2026-09-13T12:00:00.000Z",
  "observation_id": "obs_example",
  "evidence_key": null,
  "resume": {"feed":"events","after_sequence":42,"endpoint":"/v1/events"}
}

This is an illustrative shape, not a live event. feed is events or target_events. subject_id identifies the watch or destination. transition is the resulting state; previous is the prior state. State, uncertainty, checked time, observation identifier and evidence reference may be null when absent. Evidence references contain no publisher page bytes. Read evidence with your own authenticated credential; expired bytes return EVIDENCE_EXPIRED. resume.feed identifies the independent feed. resume.after_sequence gives the sequence position for recovery through the named endpoint. Maintain your own durable checkpoint from the authenticated feed so a delivered notification cannot cause you to skip earlier unseen events.

Event types

Feed	Type	Trigger
events	placement_acquired	First conclusive present result
events	placement_recovered	Present after confirmed loss/source unavailability
events	placement_changed	Present link fingerprint changes
events	placement_lost	Confirmed absence after prior presence
events	source_unavailable	Confirmed source unavailability
events	watch.checked	First check with no named transition
events	watch.state_changed	State changes with no named transition
events	watch.check_quality_changed	Uncertainty or uncertain reason changes
target_events	target_healthy	First conclusive healthy destination
target_events	target_recovered	Healthy after confirmed unavailability
target_events	target_unavailable	Confirmed destination unavailability
target_events	target.checked	First check with no named transition
target_events	target.state_changed	State changes with no named transition
target_events	target.check_quality_changed	Check uncertainty/reason changes

Confirmed absence/unavailability requires repeated conclusive evidence according to the relevant reducer; a blocked or incomplete check remains uncertain. Endpoint event-type filters advance their cursor across filtered-out types. A syntactically accepted type with no emitter matches no events.

Digest payload

Digest mode summarizes the events feed over daily or weekly windows. A payload contains:

Field	Contract
v, kind, workspace_id	Version 1, kind digest and owning workspace
window.opened_at, window.closed_at	Window boundaries
computed	true when summary was computed, even for quiet windows
totals.subjects, totals.events, totals.changed	Counts over events read for this digest
subjects	Up to 200 subject summaries
truncated	More than 200 subjects
events_truncated	More than the bounded 1000-event read
resume	Feed, last read sequence or null for a quiet window, and endpoint

Each subjects row has subject_id, project_id, previous, state, uncertain, events, types, first_seen_at, last_seen_at, checked_at and evidence_key. A subject that changes repeatedly appears once with its final state and its event count. The read limit and subject limit are separate; inspect both flags. Quiet windows are delivered with computed:true and zero totals. Digest notifications use the same signature, delivery ID and retry mechanism.

Retention gap payload

Dispatch on kind before treating a message as a normal event. When retention overtakes an endpoint cursor, a kind:"history_gap" notification has type webhook.history_gap and code CURSOR_EXPIRED. It includes id, feed, workspace_id, project_id, created_at, computed:false, totals:null and resync_required:true. history_gap contains after_sequence, through_sequence, scope:“workspace_feed”, reason:“history_unavailable” and affected_project_events:“unknown”. snapshot_endpoint names the current-state read; resume_cursor is the supplied opaque resume token. resume carries feed, after_sequence and endpoint. A digest gap also carries delivery_mode:“digest” and window. Preserve the gap explicitly. A current snapshot cannot recover expired history. The local receive command currently accepts per-event identity only. Handle digest and history-gap notifications in your receiver and use the authenticated feed/snapshot endpoints for recovery.

Retries and recovery

A 2xx response completes a delivery. HTTP 410 disables the endpoint immediately with receiver_reported_gone. Other failures retry with a ten-second send timeout and exponential backoff min(3600, 15 * 2^min(attempt,8)) seconds. Actual delivery ticks can make retries later than that minimum. Twenty consecutive failures disable the endpoint; a successful delivery resets the count. Oversized payloads above 256 KiB fail terminally. Read list_webhook_deliveries to inspect failures. Setting an endpoint active resumes pending work, but does not resend terminal failed rows. Recover missing notifications through list_link_events and list_target_events, using separate cursors. Terminal delivery rows are retained for 30 days after becoming terminal; pending rows are not pruned by that terminal-history policy.

Rotation and endpoint changes

Call rotate_webhook_secret with retire:false, save the once-returned secret, and deploy receiver support for both secrets. After verifying new-secret delivery, call it with retire:true to retire the older secret. A second rotation is refused while a rotation is open. An endpoint URL is not an editable field. Create and verify a replacement endpoint, then disable or delete the old endpoint. Deduplicate notifications while both operate. Review HTTP route differences if using resource aliases.

This reference follows the source of the deployed release. Delivery still depends on an active endpoint and enabled delivery in your hosted workspace; check capability status before depending on it.

Downloadable notification schemas

These examples come from the actual payload builders with fixture records. They are not live deliveries. Inspect kind and feed before reading a payload.

event

Download event schema

{
  "v": 1,
  "feed": "events",
  "type": "placement_acquired",
  "id": "evt_example",
  "sequence": 42,
  "workspace_id": "ws_example",
  "project_id": "prj_example",
  "subject_id": "watch_example",
  "created_at": "2026-09-13T12:00:00.000Z",
  "transition": "present",
  "previous": "unknown",
  "uncertain": false,
  "checked_at": "2026-09-13T12:00:00.000Z",
  "observation_id": "obs_example",
  "evidence_key": "evidence/example.json",
  "resume": {
    "feed": "events",
    "after_sequence": 42,
    "endpoint": "/v1/events"
  }
}

v (number, required): must equal 1
feed (string, required): must equal “events”
type (string, required): values: “placement_acquired”, “placement_recovered”, “placement_changed”, “placement_lost”, “source_unavailable”, “watch.checked”, “watch.state_changed”, “watch.check_quality_changed”
id (string, required).
sequence (integer, required): minimum: 1
workspace_id (string, required): Identifier returned by the related operation.
project_id (string, required): Identifier returned by the related operation.
subject_id (string, required): Identifier returned by the related operation.
created_at (string, required): pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$”
transition (string / null, required).
previous (string / null, required).
uncertain (boolean / null, required).
checked_at (string / null, required).
observation_id (string / null, required): Identifier returned by the related operation.
evidence_key (string / null, required).
resume (object, required): additional fields rejected
feed (string, required): must equal “target_events”
type (string, required): values: “target_healthy”, “target_recovered”, “target_unavailable”, “target.checked”, “target.state_changed”, “target.check_quality_changed”
evidence_key (null, required).
feed (string, required): must equal “citation_events”
type (string, required): values: “citation.declined”, “citation.grown”
data (object, required): additional fields rejected

All fields and nested objects

Field	Type	Presence	Meaning and constraints
`v`	number	Required	must equal 1
`feed`	string	Required	must equal “events”
`type`	string	Required	values: “placement_acquired”, “placement_recovered”, “placement_changed”, “placement_lost”, “source_unavailable”, “watch.checked”, “watch.state_changed”, “watch.check_quality_changed”
`id`	string	Required
`sequence`	integer	Required	minimum: 1
`workspace_id`	string	Required	Identifier returned by the related operation.
`project_id`	string	Required	Identifier returned by the related operation.
`subject_id`	string	Required	Identifier returned by the related operation.
`created_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`transition`	string / null	Required
`previous`	string / null	Required
`uncertain`	boolean / null	Required
`checked_at`	string / null	Required
`observation_id`	string / null	Required	Identifier returned by the related operation.
`evidence_key`	string / null	Required
`resume`	object	Required	additional fields rejected
`resume.feed`	string	Required	must equal “events”
`resume.after_sequence`	integer	Required	minimum: 1
`resume.endpoint`	string	Required	must equal “/v1/events”
`feed`	string	Required	must equal “target_events”
`type`	string	Required	values: “target_healthy”, “target_recovered”, “target_unavailable”, “target.checked”, “target.state_changed”, “target.check_quality_changed”
`evidence_key`	null	Required
`resume.feed`	string	Required	must equal “target_events”
`resume.endpoint`	string	Required	must equal “/v1/target-events”
`feed`	string	Required	must equal “citation_events”
`type`	string	Required	values: “citation.declined”, “citation.grown”
`data`	object	Required	additional fields rejected
`data.cell_id`	string	Required	Identifier returned by the related operation.
`data.current`	object	Required	additional fields rejected
`data.current.epoch_id`	string	Required	Identifier returned by the related operation.
`data.current.k`	integer	Required	minimum: 0
`data.current.n`	integer	Required	minimum: 0
`data.current.unknowns`	integer	Required	minimum: 0
`data.current.at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`data.baseline`	object	Required	additional fields rejected
`data.baseline.epoch_id`	string	Required	Identifier returned by the related operation.
`data.baseline.k`	integer	Required	minimum: 0
`data.baseline.n`	integer	Required	minimum: 0
`data.baseline.unknowns`	integer	Required	minimum: 0
`data.baseline.at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`data.comparison`	object	Required	additional fields rejected
`data.comparison.verdict`	string	Required	values: “declined”, “grown”
`data.comparison.interval`	array	Required	minItems: 2; maxItems: 2
`data.comparison.alpha`	number	Required	maximum: 1; exclusiveMinimum: 0
`data.comparison.comparisons`	number	Required	must equal 1
`data.comparison.method`	string	Required	must equal “fixed-n-hoeffding-difference”
`data.comparison.ordinal`	integer	Required	minimum: 1
`data.comparison.family_alpha`	number	Required	must equal 0.05
`data.comparison.correction`	string	Required	must equal “workspace-alpha-spending”
`data.comparison.assumptions`	string	Required
`data.evidence`	object	Required	additional fields rejected
`data.evidence.retained_observations_endpoint`	string	Required	must equal “/v1/commands/list_citation_observations”
`data.evidence.project_id`	string	Required	Identifier returned by the related operation.
`data.evidence.epoch_id`	string	Required	Identifier returned by the related operation.
`resume.feed`	string	Required	must equal “citation_events”
`resume.endpoint`	string	Required	must equal “/v1/citation-events”

digest

Download digest schema

{
  "v": 1,
  "kind": "digest",
  "workspace_id": "ws_example",
  "window": {
    "opened_at": "2026-09-12T12:00:00.000Z",
    "closed_at": "2026-09-13T12:00:00.000Z"
  },
  "computed": true,
  "totals": {
    "subjects": 1,
    "events": 1,
    "changed": 1
  },
  "subjects": [
    {
      "subject_id": "watch_example",
      "project_id": "prj_example",
      "previous": "unknown",
      "state": "present",
      "uncertain": false,
      "events": 1,
      "types": [
        "placement_acquired"
      ],
      "first_seen_at": "2026-09-13T12:00:00.000Z",
      "last_seen_at": "2026-09-13T12:00:00.000Z",
      "checked_at": "2026-09-13T12:00:00.000Z",
      "evidence_key": "evidence/example.json"
    }
  ],
  "truncated": false,
  "events_truncated": false,
  "resume": {
    "feed": "events",
    "after_sequence": 42,
    "endpoint": "/v1/events"
  }
}

v (number, required): must equal 1
kind (string, required): must equal “digest”
workspace_id (string, required): Identifier returned by the related operation.
window (object, required): additional fields rejected
computed (boolean, required): must equal true
totals (object, required): additional fields rejected
subjects (array, required): maxItems: 200
truncated (boolean, required).
events_truncated (boolean, required).
resume (object, required): additional fields rejected

All fields and nested objects

Field	Type	Presence	Meaning and constraints
`v`	number	Required	must equal 1
`kind`	string	Required	must equal “digest”
`workspace_id`	string	Required	Identifier returned by the related operation.
`window`	object	Required	additional fields rejected
`window.opened_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`window.closed_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`computed`	boolean	Required	must equal true
`totals`	object	Required	additional fields rejected
`totals.subjects`	integer	Required	minimum: 0
`totals.events`	integer	Required	minimum: 0
`totals.changed`	integer	Required	minimum: 0
`subjects`	array	Required	maxItems: 200
`subjects[].subject_id`	string	Required	Identifier returned by the related operation.
`subjects[].project_id`	string	Required	Identifier returned by the related operation.
`subjects[].previous`	string / null	Required
`subjects[].state`	string / null	Required
`subjects[].uncertain`	boolean / null	Required
`subjects[].events`	integer	Required	minimum: 1
`subjects[].types`	array	Required	minItems: 1
`subjects[].first_seen_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`subjects[].last_seen_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`subjects[].checked_at`	string / null	Required
`subjects[].evidence_key`	string / null	Required
`truncated`	boolean	Required
`events_truncated`	boolean	Required
`resume`	object	Required	additional fields rejected
`resume.feed`	string	Required	must equal “events”
`resume.after_sequence`	integer / null	Required
`resume.endpoint`	string	Required	must equal “/v1/events”

historyGap

Download historyGap schema

{
  "v": 1,
  "kind": "history_gap",
  "type": "webhook.history_gap",
  "code": "CURSOR_EXPIRED",
  "id": "whgap_whe_example_events_20",
  "feed": "events",
  "workspace_id": "ws_example",
  "project_id": "prj_example",
  "created_at": "2026-09-13T12:00:00.000Z",
  "computed": false,
  "totals": null,
  "resync_required": true,
  "history_gap": {
    "after_sequence": 5,
    "through_sequence": 20,
    "scope": "workspace_feed",
    "reason": "history_unavailable",
    "affected_project_events": "unknown"
  },
  "snapshot_endpoint": "/v1/exports/watches?projectId=prj_example",
  "resume_cursor": "eyJ2IjoxLCJ3Ijoid3NfZXhhbXBsZSIsImsiOiJldmVudHMiLCJuIjoyMH0",
  "resume": {
    "feed": "events",
    "after_sequence": 20,
    "endpoint": "/v1/events?projectId=prj_example"
  }
}

v (number, required): must equal 1
kind (string, required): must equal “history_gap”
type (string, required): must equal “webhook.history_gap”
code (string, required): must equal “CURSOR_EXPIRED”
id (string, required).
feed (string, required): must equal “events”
workspace_id (string, required): Identifier returned by the related operation.
project_id (string / null, required): Identifier returned by the related operation.
created_at (string, required): pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$”
computed (boolean, required): must equal false
totals (null, required).
resync_required (boolean, required): must equal true
history_gap (object, required): additional fields rejected
snapshot_endpoint (string, required): pattern: ”^/v1/exports/watches(?:\?projectId=[^#]*)?$”
resume_cursor (string, required): pattern: ”^[A-Za-z0-9_-]+$”
resume (object, required): additional fields rejected
delivery_mode (string, optional): must equal “digest”
window (object, optional): additional fields rejected
feed (string, required): must equal “target_events”
snapshot_endpoint (string, required): pattern: ”^/v1/targets(?:\?projectId=[^#]*)?$”
feed (string, required): must equal “citation_events”
snapshot_endpoint (string, required): pattern: ”^/v1/citation-epochs(?:\?projectId=[^#]*)?$“

All fields and nested objects

Field	Type	Presence	Meaning and constraints
`v`	number	Required	must equal 1
`kind`	string	Required	must equal “history_gap”
`type`	string	Required	must equal “webhook.history_gap”
`code`	string	Required	must equal “CURSOR_EXPIRED”
`id`	string	Required
`feed`	string	Required	must equal “events”
`workspace_id`	string	Required	Identifier returned by the related operation.
`project_id`	string / null	Required	Identifier returned by the related operation.
`created_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`computed`	boolean	Required	must equal false
`totals`	null	Required
`resync_required`	boolean	Required	must equal true
`history_gap`	object	Required	additional fields rejected
`history_gap.after_sequence`	integer	Required	minimum: 0
`history_gap.through_sequence`	integer	Required	minimum: 0
`history_gap.scope`	string	Required	must equal “workspace_feed”
`history_gap.reason`	string	Required	must equal “history_unavailable”
`history_gap.affected_project_events`	string	Required	must equal “unknown”
`snapshot_endpoint`	string	Required	pattern: ”^/v1/exports/watches(?:\?projectId=[^#]*)?$“
`resume_cursor`	string	Required	pattern: ”^[A-Za-z0-9_-]+$“
`resume`	object	Required	additional fields rejected
`resume.feed`	string	Required	must equal “events”
`resume.after_sequence`	integer	Required	minimum: 0
`resume.endpoint`	string	Required	pattern: ”^/v1/events(?:\?projectId=[^#]*)?$“
`delivery_mode`	string	Optional	must equal “digest”
`window`	object	Optional	additional fields rejected
`window.opened_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`window.closed_at`	string	Required	pattern: ”^\d{4}-\d{2}-\d{2}T.*(?:Z\|[+-]\d{2}:\d{2})$“
`feed`	string	Required	must equal “target_events”
`snapshot_endpoint`	string	Required	pattern: ”^/v1/targets(?:\?projectId=[^#]*)?$“
`resume.feed`	string	Required	must equal “target_events”
`resume.endpoint`	string	Required	pattern: ”^/v1/target-events(?:\?projectId=[^#]*)?$“
`feed`	string	Required	must equal “citation_events”
`snapshot_endpoint`	string	Required	pattern: ”^/v1/citation-epochs(?:\?projectId=[^#]*)?$“
`resume.feed`	string	Required	must equal “citation_events”
`resume.endpoint`	string	Required	pattern: ”^/v1/citation-events(?:\?projectId=[^#]*)?$”

Overview

MCP, CLI and API commands

CLI client

HTTP and events

Optional local workflows

Webhook events and delivery

Request headers and verification

Per-event payload

Event types

Digest payload

Retention gap payload

Retries and recovery

Rotation and endpoint changes

Downloadable notification schemas

event

digest

historyGap

​Request headers and verification

​Per-event payload

​Event types

​Digest payload

​Retention gap payload

​Retries and recovery

​Rotation and endpoint changes

​Downloadable notification schemas

​event

​digest

​historyGap

Request headers and verification

Per-event payload

Event types

Digest payload

Retention gap payload

Retries and recovery

Rotation and endpoint changes

Downloadable notification schemas

event

digest

historyGap