Skip to main content
Version: 8.8

Use an inbound connector

Inbound connectors enable workflows to receive data or messages from external systems or services.
Review our list of existing inbound connectors for more information.

Creating the connector event​

Inbound connectors are modeled as catch events in BPMN. Connectors can be modeled as:

  • Start events – Start a new process instance.
  • Message start events – Start a new process instance with a messageId to prevent duplicate process instance creation.
  • Intermediate catch events – Receive messages in an already running process instance.
  • Boundary events – Receive messages in an already running process instance, attached to a task.
  • Boundary events – Receive messages in an already running process instance, attached to a task.
  • Receive tasks - Receive messages in an already running process instance.
info

If idempotency is a concern for the process creation and reprocessing of messages should never lead to a duplicate process instance creation, use the message start event element for an inbound connector as it relies on publishing a message.

Unlike plain start event elements, message start events support the message ID expression property that allows you to derive a unique value from the connector output. This value is used by Zeebe to guarantee uniqueness in case other messages are published using the same Message ID.

When you deploy such a BPMN diagram with an inbound connector, the connector becomes ready to receive incoming requests. The outcome depends on the connector type:

  • Webhook connectors become available via the webhook endpoint.
  • Subscription connectors start listening to the message queue.
  • Polling connectors start polling the external system.

Modeling the connector start event​

  1. Start building your BPMN diagram with a start event building block.
  2. Change its template to an inbound connector of your choice (e.g., HTTP webhook, or a message queue subscription).
  3. Fill in all required properties.
  4. Complete your BPMN diagram.
  5. Deploy it to your Camunda 8 instance.
note

You can still start instances of that process manually via Modeler, which is sometimes useful during testing.

Example: Configuring an HTTP webhook​

Different connector types have different configuration options, but parts like Result expression, or Correlation key are common for all of them. Let's take a look at an example of configuring an HTTP webhook.

To deploy and use the webhook, you need to fill in several fields:

  1. Webhook method - HTTP method for your inbound webhook. You can either set a specific one or choose Any if all methods need to be supported.
  2. Webhook ID - Context path for your inbound webhook. This is used to build a URL endpoint for your webhook. For example, given the Webhook ID value is myWebhookPath, the complete webhook URL endpoint will be http(s)://<base URL>/inbound/myWebhookPath.
  3. HMAC authentication - If an external caller uses HMAC as a means of request validation and authentication, you can enable this property. In that case, you'll need to specify additional field values. Read more about the generic HTTP webhook configuration.
  4. Authorization - Authorization method of the webhook.
  5. Activation condition - FEEL expression that assesses trigger conditions. Note: Unlike other properties, in the activation condition, you cannot use the process variables. For example, given external caller triggers a webhook endpoint with body {"id": 1, "status": "OK"}, the Activation Condition value might look like =(request.body.status = "OK"). Leave this field empty to trigger your webhook every time.
  6. Result variable - Name of the process variable that will be created or updated with the result of the webhook. For example, if you want to save the result of the webhook in a variable called myDocumentId, you would specify myDocumentId as the Result variable value.
  7. Result expression - FEEL expression that transforms incoming body into BPMN process variables. For example, given external caller triggers a webhook endpoint with body {"id": 1, "status": "OK"} and you would like to extract id as a process variable myDocumentId. In that case, the Variable mapping might look as ={myDocumentId: request.body.id}.
  8. Response body expression - FEEL expression that forces a webhook to return a specific response. This might be useful for one-time challenge verification, or acknowledgement response. Given your webhook triggered with body {"id": 1, "status": "OK"}, if you wish to return acknowledgement, you can specify the following expression ={message: "received document ID " + string(request.body.id)} which will produce {"message":"received document ID 123"} as a response. Another example, when you wish to return a one-time subscription challenge. Given your webhook triggered with body {"event": "subscribe", "challenge":"myRandomChallenge"}. You can return challenge back with the following expression =if request.body.event = "subscribe" then request.body.challenge else null which will produce a plain string "myRandomChallenge" as a response.

If the Webhook connector is applied to an intermediate catch event, you also need to specify the following fields:

  1. Correlation key (process) - a FEEL expression that defines the correlation key for the subscription. This corresponds to the Correlation key property of a regular message intermediate catch event.
  2. Correlation key (payload) is a FEEL expression used to extract the correlation key from the incoming message. This expression is evaluated in the connector Runtime and the result is used to correlate the message.

For example, given that your correlation key is defined with requestIdValue process variable, and the request body contains {"request": {"id": 123}}, your correlation key settings will look like this:

  • Correlation key (process): =requestIdValue
  • Correlation key (payload): =request.body.request.id

See the webhook documentation or the documentation of other connector types for more details.

Connector deduplication​

In the simplest case, each inbound connector element in a BPMN diagram corresponds to a unique endpoint, event consumer, or a polling task. However, sometimes you might want to have multiple BPMN elements listening to the same event source. For example, you might want to link multiple connector events to the same message queue consumer and activate only one of them based on the message content.

Learn more about this feature in the connector deduplication guide.

Working with request context​

You can access request context in the Activation condition, Result expression, and Response body expression.

Let's consider the following cURL query: curl -X POST -H "Content-Type: application/json" -H "MyHeader: myValue" -d '{"status": "OK", "id": 123}' "http://<YOUR_HOST>/inbound/myWebhook?param1=val1".

A webhook connector context data will arrive as follows:

{
  "request": {
    "body": {
      "status": "OK",
      "id": 123
    },
    "headers": {
      "host": "YOUR_HOST",
      "user-agent": "curl/7.88.1",
      "accept": "*/*",
      "content-type": "application/json",
      "myheader": "myValue",
      "content-length": "27"
    },
    "params": {
      "param1": "val1"
    }
  },
  "connectorData": {}
}

This means in scope of the fields Activation condition, Result expression, and Response body expression, you can use not only request.body.<property> but also access headers via request.headers.myheader or params request.params.param1.

There is also a connector-specific special case of connectorData that is usually empty and used in rare cases, when body has to be crafted in a special way, but a connectors user might still want access context data.

See a list of available inbound connectors and their respective specific configuration instructions.