An API platform's requests trigger asynchronous work, webhook deliveries and retries, sometimes hours later. How should correlation identifiers be designed so a customer question can be answered end to end?

The identifiers needed

One identifier is not enough. Three are, and conflating them is the usual mistake:

1. Request id — unique per inbound API call. Returned to the customer in the response and in every error. This is what a customer quotes in a support ticket, and it must appear in every log line generated by that request.

2. Correlation id / trace id — spans the whole causal chain including asynchronous work. The original request, the queued job, the provider call, the webhook delivery and its retries all carry it. This is what answers "what happened to my message".

3. Entity id — the durable business identifier: the message, the order, the call. Survives beyond the request lifecycle and is how a customer refers to the thing rather than the operation.

Plus the idempotency key, which is customer-supplied and identifies the logical intent — distinct from all of the above, and the thing that lets a customer ask "did my retry create a second one".

The propagation rules

• Generated at the edge if absent, accepted if supplied. A customer supplying their own correlation id can trace across their system and yours, which is a genuine differentiator for a developer platform.
• Propagated through every asynchronous boundary. Queues, scheduled jobs, retries. This is where correlation is usually lost, and where it is most needed, because that is precisely the part the customer cannot see.
• Attached to every log line and every span, by the logging and tracing libraries rather than by developers remembering.
• Preserved across retries. A webhook delivery retried six hours later carries the same correlation id as the original request. Without this, the customer's question "did you try to deliver this" is unanswerable.
• Exposed to the customer, in API responses, in webhook payloads and headers, and in the delivery attempt log.

Why this matters commercially

For a platform whose customers are developers, "we cannot tell you what happened to your request" is a product defect, not an internal limitation. The identifiers are what make the platform debuggable from the outside, which converts a support conversation into self-service and eliminates the largest category of support volume.

The failure to avoid

Correlation lost at the asynchronous boundary, which is the most common implementation gap. A trace that covers the synchronous request and stops when work is enqueued answers the easy question and abandons the hard one — and for an API platform, the hard question is almost always about something that happened asynchronously, minutes or hours later.