Deliver a participant dispatch envelope (outbound)

POST

Aerandil sends this request to a participant runner’s configured HTTPS endpoint when a participant_dispatch_attempt row is claimed. The request body is a CloudEvents JSON-format envelope with type = aerandil.participant_dispatch.dispatched; the data.dispatch_kind and dataschema URI identify the specific work payload.

Signature. The envelope carries data.signature, an Ed25519 detached signature over the RFC 8785 canonical envelope with data.signature elided. Receivers resolve kid against the coordinator signing key catalogue and reject missing, expired, or unverifiable envelopes.

Receiver contract. Return any 2xx to accept transport custody. 5xx, 408, 425, 429, and transport failures are retried under the dispatcher retry policy; other non-2xx statuses are terminal for that dispatch row.

Idempotency. Deduplicate by the CloudEvents id plus data.idempotency.idempotency_key; retries reuse the same logical envelope id while stamping a fresh time.

Request Body^required

Coordinator-signed dispatch envelope (proposal 0022 §7.1).

Media typeapplication/cloudevents+json

Envelope with type = aerandil.participant_dispatch.dispatched (§7.1). Body of the outbound webhooks.aerandil_participant_dispatch request. The data.dispatch_kind and dataschema URI discriminate the concrete work payload. The v1 dispatcher emits the stable handoff fields below and may add richer scope fields as payload assembly grows.

object

data

required

Aerandil-specific payload (§5.5). Shape varies by type; the schema at dataschema is the contract.

object

datacontenttype

required

string

Allowed value: application/json

dataschema

required

URL of the schema describing data. v1 URLs are https://schema.aerandil.example/0022/...; receivers match on this to dispatch parsing.

string format: uri

id

required

UUID v7 per §5.1; reused across retries of the same logical dispatch.

string format: uuid

source

required

Producer URI; e.g. aerandil://coordinator/tenant=T-1/program=... or aerandil://participant/....

string

specversion

required

CloudEvents specversion — pinned at 1.0.

string

Allowed value: 1.0

subject

required

Composite key (e.g. <run_id>/<participation_id>/<slot>).

string

>= 1 characters

time

required

RFC 3339; checked against the ±5-minute replay window.

string format: date-time

type

required

Reverse-DNS message kind.

string

Allowed values: aerandil.participant_dispatch.dispatched aerandil.participant_dispatch.acknowledged aerandil.participant_dispatch.result_submitted aerandil.participant_dispatch.delivery_failed aerandil.participant_dispatch.quarantine_notice

data

required

object

coordinator

required

object

aerandil_coordinator_identity_ref

string format: uri-reference

aerandil_correlation_id

string

aerandil_run_id

string

>= 1 characters

aerandil_tenant_id

string

>= 1 characters

key

additional properties

any

dispatch_kind

required

string

>= 1 characters

envelope_version

required

string

Allowed value: 1.0

idempotency

required

object

dispatch_attempt

required

integer

>= 1

envelope_expires_at

required

string format: date-time

idempotency_key

required

string

>= 1 characters

participant

required

object

aerandil_participation_id

string

>= 1 characters

agent_installation_id

string | null

local_execution_mode

string

Allowed values: operator_runner agent_installation hosted_connector third_party_clean_room secure_aggregation

participant_object_ref

string | null

participant_scope

string

Allowed values: tenant property venue channel

runner_identity_ref

string format: uri-reference

key

additional properties

any

scope

object

aggregation_protocol

string

Allowed values: plain_aggregate_reviewed secure_aggregation clean_room_query

contribution_kinds_admissible

Array<string>

deadline_at

string format: date-time

input_window_end

string format: date-time

input_window_start

string format: date-time

local_code_digest

string

/^sha256:[0-9a-f]{64}$/

minimum_local_runner_version

string

payload_size_bytes_max

integer

>= 1

recommended_local_runner_version

string

scope_schema_version

string

Allowed value: 1.0

key

additional properties

any

signature

required

Ed25519 detached signature over the canonical bytes of the surrounding envelope (RFC 8785 JCS with the signature field elided). Proposal 0022 §8.2.

object

alg

required

Signature algorithm — v1 supports ed25519 only.

string

Allowed value: ed25519

kid

required

Key identifier. Resolves against federated_participation.runner_signing_key_ref for participant-signed envelopes, or the coordinator signing config for coordinator-signed.

string

>= 1 characters

value

required

Base64 (RFC 4648 §4) detached signature bytes.

string

>= 1 characters

key

additional properties

any

dataschema

required

Stable schema URI for data; normally <dataschema_base>/dispatch/{dispatch_kind}.v1.json.

string format: uri

type

required

Allowed value: aerandil.participant_dispatch.dispatched

Responses

200

Receiver accepted the dispatch. Any 2xx status counts as success; Aerandil reads only the status code.

default

Non-2xx response. Retryable statuses follow proposal 0022 §11.2 (5xx, 408, 425, 429); all other statuses are terminal.