Correlation IDs for Structured Events

A correlation ID connects records created by the same workflow. It can link an inbound request to a queued job, a webhook to a billing sync, or a structured outcome event to an existing trace.

Choose an ID with one meaning

Name the identifier for the thing it represents: request_id, trace_id, job_id, webhook_delivery_id, or workflow_run_id. A generic correlation_id is harder to use when different services attach different meanings to it.

Generate the value at the earliest trustworthy boundary and pass it explicitly through downstream work. Preserve an upstream trace ID when it is already available. For asynchronous jobs, store both the originating request or workflow ID and the job system’s own ID when each answers a different question.

Do not use email addresses, access tokens, or raw provider payloads as correlation values. An opaque internal identifier is easier to rotate and safer to expose in a query result.

Query a workflow

Once related tables share an identifier, SQL can reconstruct the sequence:

SELECT
  timestamp_utc,
  event_name,
  status,
  duration_ms,
  error_type
FROM workflow_events
WHERE workflow_run_id = 'run_example'
ORDER BY timestamp_utc;

For aggregate dashboards, group by stable categories rather than the ID itself. Keep correlation IDs in a recent-failures table or a drill-down query so engineers can move from a rate to concrete examples.

Avoid common breaks

Do not generate a new request ID in each service. Do not overload one field with a request ID on some rows and an account ID on others. Confirm retries keep the workflow ID while receiving a distinct attempt or delivery ID. If the value crosses a trust boundary, validate its format and length before logging it.

Correlation creates navigability, not causality by itself. Document how the value is propagated and which event owns the final outcome.

Pair this guide with logs, metrics, traces, and events and high-cardinality fields.