#Start a process from an incoming request

A message start event starts a process whenever an external system sends a request, either to a webhook Chester registers on deploy or to a fixed URL you hand out.

#Two ways in

Which way applies is decided by the inbound action the start event uses — see Systems and adapters:

sequenceDiagram
  participant X as External system
  participant C as Chester
  participant P as Process
  Note over C,X: Webhook mode: on deploy, Chester registers the webhook
  X->>C: Request
  C->>C: Answer a handshake, if it is one — nothing starts
  C->>C: Check the signature or API key
  C->>C: Apply the filter
  C->>C: Skip it if it is a duplicate
  C->>P: Start an instance with the request's data

#Configure a message start event

1. Connection settings → Action: pick the system, the inbound adapter and the inbound action. Optionally choose an Environment, and a Credentials override if this element needs different permissions than the environment gives.
2. Fill in the groups the action asks for. Which appear depends on the action — for example the request body for the webhook registration, or a Delta query that fetches the changed records after each notification.
3. Correlation → Correlation Key (optional) sets the end of the static URL. It may only contain letters, digits and -, _, ., ~. Without it, the element's id is used.
4. Filter → Filter (optional): a condition on the incoming request. Only requests for which it is true start the process. It can use payload, headers and query — nothing from the process, because none exists yet. Leave it empty to start on every request.

Signature checks and API keys are set on the adapter, transformations and duplicate detection on the action — not on the element. A static URL needs one of the two: an adapter with neither an API key nor a signature check refuses every request with 401, and the process editor shows an error on this element until the adapter has one. The external system sends the key in the X-API-Key header, or as Authorization: Bearer …. See Receive requests with a webhook adapter.

⚠️ The URL the adapter shows, …/api/workflow/start/<adapter id>, does not start this process. Give the external system …/api/workflow/start/<correlation key> instead.

#Know whether the webhook is registered

Registration runs in the background after the deployment, so a deploy succeeds even if the external system refuses the webhook. The process list and the deployment show the state:

• Webhook active
• Registering webhook …
• Webhook registration failed
• Webhook expired

A webhook is renewed before it expires, and survives a restart of Chester.

#The data it provides

Under the start event's id, the process finds the request body — in webhook mode after the action's transformations. _inbound — at the top of the process data, not under the start event's id — holds the raw request: payload, headers and query, with credentials removed, and when it arrived. (A message catch event keeps its _inbound under its own id.) With a delta query, the start event's data holds rawResponse, deltaResponse and, with a transform, deltaTransformation — see Configure an inbound action. An empty delta starts nothing.

The initiator of such a run is the system, not a person.

#Limits

• ⚠️ Start Condition (optional), in the Delta query group, is saved but never evaluated. Use the Filter instead.
• ⚠️ A static URL accepts JSON only, and ignores the action's transformations: the process receives the body exactly as it was sent.
• ⚠️ A static URL is shared by every active deployment of the process. While a development and a production deployment are both active, one request starts two instances.
• ⚠️ The correlation key's help text suggests a variable such as ${context.triggerType}. Validation refuses $, { and } — the key is a fixed text.
• ⚠️ If an external system retries a request that failed to start the process while duplicate detection is on, the retry counts as a duplicate and no instance is created.
• ⚠️ The validation messages of this element are German, whatever the language of the screen.