#Wait for an incoming message

An intermediate message catch event holds the process until an external system sends a matching request — by webhook, to a static URL, or through the API — and files the request's data under its id.

#What happens when the process reaches it

sequenceDiagram
  participant P as Process
  participant C as Chester
  participant X as External system
  P->>C: Reach the catch event — start waiting
  C->>X: Webhook mode: register a webhook for this wait
  X->>C: Request
  C->>C: Find the waiting process, apply the filter
  C->>P: Continue, with the request under the catch event's id
  C->>X: Webhook mode: remove the webhook again

How the request finds the right waiting process depends on how it arrives:

A process that is waiting survives a restart of Chester.

#Configure a message catch event

1. Connection settings → Action: pick the system, the inbound adapter and the inbound action. Optionally an Environment, and Credentials if this element needs different permissions.
2. Fill in the groups the action asks for — for example Registration request body for the webhook registration, or Delta query to fetch the changed records after a notification.
3. Correlation → Correlation ID (optional): an expression evaluated when the process reaches the event, usually a value from the process — such as StartEvent_1.orderId. A static-URL or API request carrying the same value continues this process.
4. Filter → Filter (optional): a condition on the incoming request, using payload, headers and query. Only a request for which it is true continues the process.

Signature checks, API keys and transformations are set on the adapter and the action. See Systems and adapters. A static URL needs an API key or a signature check on the adapter: with neither, every request is refused with 401 and no waiting process continues — the process editor marks this element with an error.

#Give up after a while

A message catch event has no time limit of its own and cannot carry a boundary event. To stop waiting after a while, put it behind an event-based gateway next to a timer event: whichever happens first is taken, and the webhook of the other path is removed. See Gateways.

#The data it provides

Under the catch event's id the next steps find the request body — in webhook mode after the action's transformations — for example MessageCatch_reply.status. With a delta query, they find rawResponse (the notification), deltaResponse (the delta query's answer) and, with a transform, deltaTransformation — see Configure an inbound action. _inbound under the same id holds the raw request: payload, headers and query, with credentials removed, and when it arrived.

⚠️ The variable list offers the body's fields, but not _inbound.

#What a message catch event cannot do

• ⚠️ Webhook mode needs a challenge. The webhook can be registered only if the adapter's Challenge & signature settings use a challenge of type HMAC or custom token. Without one, registration fails every time and the process waits for good — the instance view shows nothing but a waiting step.
• ⚠️ Tell processes apart by webhook alone. Without a per-wait challenge, one webhook request continues every process waiting at this event. The Correlation ID is not used for webhooks; separate them with the Filter.
• ⚠️ Compare with process data in the filter. The filter sees only the request — it cannot check a reply against, say, the order number the process is waiting for.
• ⚠️ Correlation ID help text. It suggests a value such as ${context.orderId} and says the ID sets an endpoint path. The field is an expression: write StartEvent_1.orderId, or a fixed text in quotes. If the expression cannot be worked out, the text itself is used as the ID — the same for every process.
• ⚠️ Start Condition (optional), in the Delta query group, is saved but never evaluated. Use the Filter instead.
• ❌ Keep a message for later. A request that arrives before the process reaches the event is not stored. It continues nothing — and a webhook request is still answered as received, so the external system does not send it again.
• ❌ A time limit of its own — see above.

#What validation checks

A system, an inbound adapter and an inbound action must be selected, and the fields the action marks as required for the registration must be filled in. An inbound adapter without an address of its own needs an Environment. The Filter must be a condition and the Correlation ID a text.

The messages are shown in German. See Check that a process can run.