Correlation ID Guide
Route external events — webhooks, payment callbacks, approvals — back to the exact running process instance that is waiting for them.
How correlation works
When a process reaches an intermediate catch event or receive task, it pauses and waits for a matching message. You publish the message via POST /api/v1/messages with a correlation key — typically a business identifier like an order ID or payment reference — that matches a variable in the waiting instance.
Priostack evaluates all waiting subscriptions and delivers the message to the correct instance. Multiple instances can be waiting on the same message name with different correlation keys; each receives only the message intended for it.
A correlation ID in your observability stack (e.g. a request header X-Correlation-ID) is separate: it is a trace identifier you can store as a process variable to link your external log entries to the process instance.
Delivers a message to all process instances waiting on the given message name whose correlation key variable matches the provided value.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
messageName | string | required | The message name as declared in the BPMN catch event or receive task. |
correlationKey | string | required | Value of the correlation variable (e.g. the order ID). |
variables | object | optional | Variables to merge into the instance scope on delivery. |
timeToLive | integer | optional | Milliseconds to buffer the message for instances not yet waiting. Defaults to 0 (no buffering). |
Example: Stripe webhook triggers payment confirmation
{
"messageName": "payment-confirmed",
"correlationKey": "ORD-42",
"variables": {
"chargeId": "ch_stripe_abc",
"paidAt": "2026-04-06T09:10:00Z"
}
}
Example response 200 OK
{
"messageKey": "msg_def456",
"instancesCorrelated": 1
}
Pass your observability correlation ID (e.g. from an upstream HTTP request) as a process variable at instance start. This allows you to join logs from external systems with the Priostack audit trail.
Example request
{
"processDefinitionKey": "payment-process",
"variables": {
"orderId": "ORD-42",
"correlationId": "req-7f3a9b12-trace"
}
}
You can later query the instance by variable value: GET /api/v1/process-instances?variables=correlationId:req-7f3a9b12-trace
Returns all message subscriptions for a running process instance — useful for debugging when an expected message has not arrived.
Example response 200 OK
{
"subscriptions": [
{
"messageName": "payment-confirmed",
"correlationKeyVariable": "orderId",
"correlationKeyValue": "ORD-42",
"elementId": "catch_payment_confirmed",
"since": "2026-04-06T09:00:10Z"
}
]
}
In your BPMN, add an Intermediate Message Catch Event or Receive Task. Set the message name to match the messageName you will publish. Set the correlation key expression (in the subscriptionCorrelationKey extension) to the process variable that holds your business ID, e.g. =orderId.