Machine-scoped webhook ingest.

POST

/api/v1/ingest/webhook/{source_id}

curl --request POST \
  --url https://example.com/api/v1/ingest/webhook/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '"example"'

Authenticated by the per-source bearer token rather than a session — see the module doc. The three token outcomes are deliberately distinct: a wrong token is 401 bad_token, an unknown or disabled source is 404, and a source over its rate is 429. A sender needs to tell “fix my token” from “that source is gone” from “slow down”.

Authorizations

• bearer

Parameters

Path Parameters

source_id

required

string format: uuid

Webhook source id

Request Body^required

Arbitrary sender payload; a JSON object’s message/text/summary becomes the event text

Media typeapplication/json

string

Example^generated

example

Responses

202

Event accepted

Media typeapplication/json

The accepted event’s id.

object

event_id

required

string format: uuid

Example^generated

{
  "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

401

Missing or wrong per-source ingest token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

No enabled webhook source with that id

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

413

Body over the per-request ingest cap

429

This source is over its ingest rate limit

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Event ingestion is not configured, or this core is not the HA leader

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}