Correlation ID Guide
Link external events - webhooks, payment callbacks, approvals - and your own logs to the process instance they belong to, and move a waiting instance on.
How correlation works today
The hosted API has no endpoint that publishes a BPMN message or signal, and none that lists an instance's message subscriptions. Message correlation by key is therefore not available over REST.
When a process reaches a receive task or an intermediate message or signal catch event, the wait becomes an ordinary job in the queue. Its job type is message:<messageName> for a receive task that references a message, event:message:<elementId> for a message catch event, and event:signal:<elementId> for a signal catch event. A worker that activates that type and completes the job moves the instance on. Nothing matches a correlation key on this path: before completing, your worker must check that the instance's variables (an order ID, a payment reference) are the ones the external event is about.
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. The incident routes also echo an X-Correlation-ID request header back.
When your external event arrives (for example a Stripe webhook for order ORD-42), activate the waits of that type, complete the one whose instance is about that order, and fail the others with their retries unchanged so they go straight back to the queue.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | required | The wait's job type, e.g. message:payment-confirmed. Always send it: an activation with no type hands out every waiting job, message waits included. |
maxJobsToActivate | integer | optional | Caps the batch. Omitted or 0 activates every waiting job of that type. |
Example: Stripe webhook confirms a payment
# 1. Activate the waits for this message
POST /api/v1/jobs/activate
{ "type": "message:payment-confirmed", "maxJobsToActivate": 10 }
# 2. For the job whose variables.orderId is "ORD-42", complete it (204 No Content)
POST /api/v1/jobs/a99f579d62ae71f8764f/complete
{ "variables": { "chargeId": "ch_stripe_abc", "paidAt": "2026-09-29T09:10:00Z" } }
# 3. Hand every other activated job back without using a retry (204 No Content)
POST /api/v1/jobs/{key}/fail
{ "retries": 3, "errorMessage": "not the order this event is about" }
Send back the retries value the job arrived with: the server stores the number you send, so the job loses no attempt.
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
{
"bpmnProcessId": "payment-process",
"variables": {
"orderId": "ORD-42",
"correlationId": "req-7f3a9b12-trace"
}
}
You can later find the instance by variable value: GET /api/v1/process-instances?filter.variable=correlationId:req-7f3a9b12-trace. The match is a case-insensitive substring match on that one variable.
Returns every job of yours that is waiting to be activated, without activating any. A message or signal wait shows up with its job type, so filter the list on processInstanceKey to see what one instance is waiting for.
Example response 200 OK
{
"jobs": [
{
"key": "a99f579d62ae71f8764f",
"type": "message:payment-confirmed",
"processInstanceKey": "run_1ce49bbc5260b39423bd",
"processDefinitionKey": "3f9c2a7e5b1d8c4e6a02",
"variables": { "orderId": "ORD-42" },
"retries": 3,
"deadline": 0,
"createdAt": "2026-09-29T09:00:10Z"
}
],
"total": 1
}
In your BPMN, add an Intermediate Message Catch Event or Receive Task that references a message. The engine reads a correlation key declared on the message itself, as <zeebe:subscription correlationKey="=orderId" /> inside the <bpmn:message> element's extensionElements, naming one process variable. The hosted API does not publish messages against that key today, so on priostack.com the wait is completed by a worker as shown above.