Guide · Events & telemetry

Observe, without taking over.

Send webhooks and OpenTelemetry traces from systems you already run. Ardyn holds no write credential for them and changes nothing there. It reconstructs an operation from what it received, and marks missing stages instead of assuming success.

Webhooks — profile ardyn-webhook/1

POST /v1/connections
{"family": "webhook", "name": "Dispatch system",
 "config": {"id_field": "event_id", "correlation_field": "job_id",
            "stage_field": "stage", "time_field": "occurred_at",
            "required_fields": ["job_id"], "schema_version": "1"}}

The response includes ingest_secret once. Deliveries go to POST /v1/ingest/webhook/<connection id> with:

X-Ardyn-Timestamp: <unix seconds>
X-Ardyn-Signature: sha256=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>

LimitsJSON object ≤ 256 KiB; ±300 s replay window

IdentityThe source’s own event id. A transport or ingestion id is never relabelled as the provider’s id.

OpenTelemetry — profile ardyn-otlp-http-json/1

exporters:
  otlphttp/ardyn:
    traces_endpoint: https://<runtime>/v1/ingest/otlp/<connection id>/v1/traces
    encoding: json
    headers:
      Authorization: "Bearer <ingest token>"

SignalsTraces, OTLP/HTTP with JSON encoding. Protobuf, gRPC, metrics and logs are not supported (refused with a reason).

IdentityEach span is recorded as traceId:spanId, with its start time as event time

CorrelationFrom the span attributes you configure (default ardyn.correlation_id, ardyn.stage)

Tested withThe OpenTelemetry Collector v0.162.0 (pinned build) exporting to a real runtime

Reconstruct one operation

POST /v1/reconstruct  {"correlation_id": "job-8f3a", "expected_stages": ["queued", "accepted", "dispatched", "completed"]}

{"observations": 4, "missing_stages": [], "verify_class": "SUPPORTED", "receipt_id": "…"}

Declare a stage that never arrived and the result becomes PARTIALLY_SUPPORTED, with EVENT_GAP and EXTERNAL_EFFECT_UNCONFIRMED — never a success.

DuplicatesThe same event id and payload is accepted once; retries are not new events

Same id, different payloadBoth are kept and reported as a conflict (CONFLICTED)

Late eventsAccepted; ordered by event time, with receipt time kept

RejectedBad signature (401), outside the replay window, wrong schema version, oversized (413), unknown endpoint (404), another workspace’s secret (401)

RestartAccepted observations survive a runtime restart without loss or duplication

DisconnectRevoking stops new deliveries (410). Existing receipts stay exportable.

Correlation ids link observations; they don’t prove one step caused another. Sampled or uninstrumented work stays a visible limit.