Skip to main content
Version: Next

HTTP Webhook Connector

The HTTP Webhook Connector is an inbound Connector that allows you to start a BPMN process instance triggered by external HTTP call.

note

If you have used the HTTP Webhook Connector with a self-managed Camunda 8 configuration before the Connector SDK 0.7.0 release, you might need to manually replace the element template. Please refer to the update guide for more details.

Create an HTTP Webhook Connector event​

  1. Start building your BPMN diagram. You can use HTTP Webhook Connector with either Start Event or Intermediate Catch Event building blocks.
  2. Select the applicable element and change its template to an HTTP Webhook.
  3. Fill in all required properties.
  4. Complete your BPMN diagram.
  5. Deploy the diagram to activate the webhook.
  6. Navigate to the Webhooks tab in the properties panel to see the webhook URL.

Make your HTTP Webhook Connector executable​

  1. In the Webhook Configuration section, configure the Webhook ID. By default, Webhook ID is pre-filled with a random value. This value will be part of the Webhook URL. You will find more details about HTTP Webhook URLs below.

  2. Configure HMAC authentication if required in the Authentication section: If you require HMAC authentication for your webhook, you can set up the HMAC shared secret key, HMAC header, HMAC hash algorithm, and an array of HMAC scopes.

    • HMAC secret key: Set the HMAC shared secret key that will be used to calculate the message hash. The value of this key should be provided by the webhook provider to ensure secure communication.

    • HMAC header: Set the HMAC header whose value contains an encrypted hash message. The exact value of this header should be provided by the external caller when invoking your webhook.

    • HMAC hash algorithm: Select the HMAC hash algorithm to be used in the HMAC signature calculation. The exact value of this algorithm should also be provided by the external caller when invoking your webhook.

    • HMAC Scopes (optional): Here, you can define an array of HMAC scopes to specify which parts of the webhook request are included in the HMAC signature calculation. The available HMAC scopes are:

      • BODY (default value): Includes the body of the webhook request in the HMAC signature calculation.
      • URL: Includes the URL of the webhook request in the HMAC signature calculation.
      • PARAMETERS: Includes the query parameters of the URL in the HMAC signature calculation.

      Example: =["URL","PARAMETERS"]

      Based on the selected HMAC scopes and the HTTP method used in the webhook request, the system will automatically determine the appropriate HMAC strategy to be used. The supported HMAC strategies are:

      • Body Encoding Strategy (default): This strategy is used when the HMAC scopes only include BODY or empty. The signature data for the HMAC signature is generated from the body of the webhook request.

      • URL and Parameters Encoding Strategy: This strategy is used when the HMAC scopes include URL, and PARAMETERS, and the HTTP method is GET. The signature data for the HMAC signature is generated by combining the URL and the parameters of the webhook request.

      • URL and Body Encoding Strategy: This strategy is used when the HMAC scopes include URL, BODY. When the HTTP method is GET, it uses the URL and Parameters Encoding Strategy instead. The signature data for the HMAC signature is generated by combining the URL and the body of the webhook request.

        Example for URL and Parameters Encoding Strategy: Let's consider a sample webhook request:

        HTTP Method: GET
        Webhook URL: "https://example.com/webhook?id=123456&name=John%20Doe"

        In this example, the HMAC strategy will combine the URL and the query parameters to generate the signature data for the HMAC signature. The URL-encoded query parameters will be sorted alphabetically, and then, they will be concatenated with the URL: Signature Data: https://example.com/webhook?name=John%20Doe&id=123456 The Signature Data will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.

        Example for URL and Body Encoding Strategy: Let's consider another sample webhook request:

        HTTP Method: POST
        Webhook URL: `https://example.com/webhook`
        Webhook Body: `{"id": 123456, "name": "John Doe", "age": 30}`

        In this example, the HMAC strategy will combine the URL and the body of the webhook request to generate the signature data for the HMAC signature: Signature Data: https://example.com/webhook{"id":123456,"name":"John Doe","age":30} The Signature Data will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.

  3. Configure authorization if required in the Authorization section. The HTTP Webhook Connector supports the following authorization methods:

  • Basic - The incoming requests must contain an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

    • Set the Username and Password properties which will be used to validate the incoming requests.
    • Provide the values in plain text, not base64-encoded.

  • API Key - The API key can be provided anywhere in the request, for example, in the Authorization header or in the request body.

    • Set the API Key property to the expected value of the API key.
    • Set the API Key locator property that will be evaluated against the incoming request to extract the API key. See the example.

  • JWT authorization - The token should be in the Authorization header of the request in the format of Bearer {JWT_TOKEN}.

    • Set JWK URL which is used as a well-known public URL to fetch the JWKs.
    • Set JWT role property expression which will be evaluated against the content of the JWT to extract the list of roles. See more details on extracting roles from JWT data here.
    • Set the required roles which will be used to validate if the JWT contains all required roles. See more details on extracting roles from JWT data here.
  1. Configure Activation Condition. For example, given external caller triggers a webhook endpoint with the 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.
  2. Use Variable Mapping to map specific fields from the request into process variables using FEEL. For example, given the external caller triggers a webhook endpoint with the body {"id": 1, "status": "OK"} and you would like to extract id as a process variable myDocumentId, the Result Expression might look like this:
= {
  myDocumentId: request.body.id
}
  1. Fill in the Correlation parameters if they are required by the element template.

Correlation​

The Correlation section allows you to configure the message correlation parameters.

note

The Correlation section is not applicable for the plain start event element template of the Webhook Connector. Plain start events are triggered by process instance creation and do not rely on message correlation.

Correlation key​

  • Correlation key (process) is 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.
  • 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 orderId process variable, and the request body contains {"orderId": "123"}, your correlation key settings will look like this:

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

Learn more about correlation keys in the messages guide.

Message ID expression​

The Message ID expression is an optional field that allows you to extract the message ID from the incoming request. The message ID serves as a unique identifier for the message and is used for message correlation. This expression is evaluated in the Connector Runtime and the result is used to correlate the message.

In most cases, it is not necessary to configure the Message ID expression. However, it is useful if you want to ensure message deduplication or achieve a certain message correlation behavior. Learn more about how message IDs influence message correlation in the messages guide.

For example, if you want to set the message ID to the value of the transactionId field in the incoming message, you can configure the Message ID expression as follows:

= request.body.transactionId

Message TTL​

The Message TTL is an optional field that allows you to set the time-to-live (TTL) for the correlated messages. TTL defines the time for which the message is buffered in Zeebe before being correlated to the process instance (if it can't be correlated immediately). The value is specified as an ISO 8601 duration. For example, PT1H sets the TTL to one hour. Learn more about the TTL concept in Zeebe in the message correlation guide.

Activate the HTTP Webhook Connector by deploying your diagram​

Once you click the Deploy button, your HTTP Webhook will be activated and publicly available. You can trigger it by making a POST request to the generated URL.

URLs of the exposed HTTP Webhooks adhere to the following pattern:

http(s)://<base URL>/inbound/<webhook ID>>

  • <base URL> is the URL of Connectors component deployment. When using the Camunda 8 SaaS offering, this will typically contain your cluster region and cluster ID.
  • <webhook ID> is the ID (path) you configured in the properties of your HTTP Webhook Connector.

If you make changes to your HTTP Webhook Connector configuration, you need to redeploy the BPMN diagram for the changes to take effect.

When you click on the event with HTTP Webhook Connector applied to it, a new Webhooks tab will appear in the properties panel. This tab displays the URL of the HTTP Webhook Connector for every cluster where you have deployed your BPMN diagram.

note

The Webhooks tab is only supported in Web Modeler as part of the Camunda 8 SaaS offering. You can still use HTTP Webhook Connector in Desktop Modeler, or with your Camunda 8 Self-Managed. In that case, HTTP Webhook Connector deployments and URLs will not be displayed in Modeler.

Example​

Give a use-case when you need to configure a GitHub webhook with an HTTP Webhook Connector in such a way that: (1) your BPMN process starts on every opened PR, and (2) the PR URL is exposed as a process variable. Let's say you choose mySecretKey as a shared secret passphrase. GitHub declares that they use X-Hub-Signature-256 header for SHA-256 HMAC. Therefore, you would need to set the following:

  1. Webhook ID: any unique to your cluster webhook ID. This will generate a URL to trigger your webhook. In example, myWebhookPath.
  2. HMAC Authentication: enabled.
  3. HMAC Secret Key: mySecretKey or {{secrets.MY_GH_SECRET}}.
  4. HMAC Header: X-Hub-Signature-256.
  5. HMAC Algorithm: SHA-256.
  6. HMAC Scopes: =["BODY"] or leave empty.
  7. Activation Condition: =(request.body.action = "opened").
  8. Variable Mapping: ={prUrl: request.body.pull_request.url}.
  9. Click Deploy.

How to configure API key authorization​

External callers can provide an API key anywhere in the requests. Some webhook providers use an Authorization header, while others pass the API key in the request body. To support any scenario, you can configure the HTTP Webhook Connector to extract the API key from the request.

Use the API Key locator field to provide a FEEL expression that will be evaluated against the request to extract the API key. The result of this expression will be used as the API key and compared against the expected API key value.

Use the API Key field to provide the expected API key value.

API key locator examples​

Suppose an external caller triggers a webhook endpoint with the following request body:

{
  "id": 1,
  "status": "OK",
  "secret": "my_secret"
}

You want to extract the secret field and use it as the API key to authorize the webhook request. In this case, you can set the API Key locator to:

=request.body.secret

The expression above will be evaluated to my_secret, which will be used as the API key.

Alternatively, you can use the API Key locator to extract the API key from the Authorization header:

=request.headers.authorization

If your Authorization header contains the Bearer prefix, you can use the split function to remove it:

=split(request.headers.authorization, " ")[2]

How to extract roles from JWT data​

To extract roles from the JWT payload, specify the JWT role property expression using the FEEL expression syntax.

note

This expression will be evaluated only against the JWT payload, therefore you cannot access process variables or secrets here.

JWT payload and role property expression example​

Let's observe a typical JWT payload example below:

{
  "iss": "https://idp.local",
  "aud": "api1",
  "sub": "5be86359073c434bad2da3932222dabe",
  "client_id": "my_client_app",
  "exp": 1786822616,
  "iat": 1686819016,
  "jti": "114f8c84c53703ac2120d302611e358c",
  "roles": ["admin", "superadmin"],
  "admin": true
}

To extract the roles you can set the JWT role property expression to:

if admin = true then ["admin"] else roles

Note: the result of this expression should always be an array.

In this particular case, the if statement is evaluated to true, the extracted roles will be:

["admin"]

If you provide ["admin"] for Required roles, the message can be correlated.

If you provide ["superadmin"] or ["admin","superadmin"], for Required roles, for example, the message can NOT be correlated and the Connector will throw an exception.

note

For GitHub, there is a simplified GitHub Webhook Connector.

Return data from your HTTP Webhook Connector​

Below, find several ways to return data from your Webhook Connector.

Verification expression​

Verification expression is used whenever a webhook needs to return response data without starting a process. A common use-case may be a one-time verification challenge.

For example, consider the following verification challenge from Slack:

{"token": "Jhj5dZrVaK7ZwHHjRyZWjbDl","challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P","type": "url_verification"}

To confirm the Slack events subscription, you must return the following response:

HTTP 200 OK Content-type: application/json {"challenge":"3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"}

To do so, the Verification expression field may look like:

=if request.body.type = "url_verification" then {"body": {"challenge": request.body.challenge}, "statusCode": 200} else null.

When working with request data, use the following references to access data:

  • Body: request.body..
  • Headers: request.headers..
  • URL parameters: request.params..

When working with response, you can use the following placeholders:

  • Body: "body", for example {"body": {"challenge": request.body.challenge}}.
  • Status code: statusCode, for example {"statusCode": 201, "body": {"challenge": request.body.challenge}}.
  • Headers: headers, for example {"headers": {"X-Challenge": request.body.challenge}, "body": {"challenge": request.body.challenge}}.

You can also use FEEL expressions to modify the data you return.

Response expression​

note

Prior to 8.6, the HTTP Webhook Connector supported a response body expression. As of 8.6, this was replaced with a more powerful construct that allows control over not only the response body, but also the headers and the HTTP status returned by the Connector.

A response expression can be used to return data after the webhook has been invoked. You can use FEEL to return the body, headers, and the HTTP status to the client invoking the Webhook Connector endpoint.

For example, given a webhook request with the payload body:

{
  "myDataKey1": "myValue1",
  "myDataKey2": "myValue2"
}

You can return myValue1 in a new key myCustomKey with a response body expression that may look like this:

={
  "body": {"myCustomKey": request.body.myDataKey1}
}

The default HTTP status code is 200. You can change it by providing a statusCode key in your expression:

={
  "body": "hello",
  "statusCode": 201
}

Headers are also supported by using the headers key in the response expression:

={
  "headers": {"Content-Type": "text/html"},
  "body": "<h1>Hello world!</h1>"
}

When working with request data, use the following references to access data:

  • Body: request.body..
  • Headers: request.headers..
  • URL parameters: request.params..

You can also use FEEL expressions to modify the data you return.

In addition to the request object you have access to the correlation result.

The data available via the correlation object depends on the type of BPMN element you are using the Webhook Connector with.

A start event with a message definition uses message publishing internally to correlate an incoming request with Zeebe. A successful correlation will therefore lead to a published message and the correlation object will contain the following properties:

{
  "messageKey": 2251799813774245,
  "tenantId": "<default>"
}

If a Webhook request is processed more than once using the same Message ID (because of a retry for example) the correlation object will be empty.

A start event without a message will create a new process instance. You therefore have access to the newly create process instance key when accessing the correlation object:

{
  "processInstanceKey": 6755399441144562,
  "tenantId": "<default>"
}