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.

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.

4. 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.
5. 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
}

6. If you are using the HTTP Webhook Connector with an Intermediate Catch Event, fill in the Correlation key (process) and Correlation key (payload).

• 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.

7. To avoid double message submission, you can set a unique message ID by using Message ID expression field, for example, =request.body.orderId. A request with the same value evaluated by Message ID expression will be rejected.

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.

note

HTTP Webhook Connector currently supports only POST requests.

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 body expression

Response body expression can be used to return data after webhook has been triggered. You can craft a response body based on your needs. For example, given a webhook request {"myDataKey1":"myValue1", "myDataKey2":"myValue2"}, you can return myValue1 in a new key myCustomKey with a response body expression that may look like this: ={"myCustomKey": request.body.myDataKey1}.

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.