Webhook Integrations
Webhooks are HTTP callback functions that enable Orkes Conductor to interact with external systems in real time. When an event occurs on an external platform, a webhook sends event data to Conductor. This enables:
- Workflows (containing webhook tasks) to act on external events.
- To trigger other workflows in response to incoming webhook events.
Orkes Conductor supports webhook integration with the following platforms:
- GitHub
- Microsoft Teams
- SendGrid
- Slack
- Stripe
In addition, you can integrate it with any other system using the Custom platform option.
Overview
This guide explains how to integrate Webhook with Orkes Conductor. Here’s an overview:
- Create a workflow including a Wait for Webhook task
- Create a webhook in Orkes Conductor
- Verify webhook
- Run workflow
Webhook payloads can trigger workflows in different ways, depending on your use case:
- If a workflow must wait for a specific webhook event–Create a workflow that includes a Wait for Webhook task with input matches defined based on the expected webhook payload. Proceed to Step 1.
- If a webhook event must trigger a new workflow–Configure the webhook to start a separate workflow when the event is received. In this case, you can skip Step 1, and proceed directly to Step 2.
- If you need both behaviors–Configure the webhook to send its payload to the workflow containing a Wait for Webhook task while also triggering a separate workflow.
Step 1: Create a workflow
To create a workflow:
- Go to Definitions > Workflow from the left menu on your Orkes Conductor cluster.
- Select + Define Workflow.
- In your visual workflow builder, select the (+) icon and add a Wait for Webhook task.
- Configure the input matches to align with the payload structure expected from the incoming webhook platform.
- Save the workflow definition.
Run the workflow before the webhook event is received. The workflow will pause at the Wait for Webhook task and resume only when an incoming event matches the configured criteria.
Step 2: Create a webhook
The next step is to create a webhook in Orkes Conductor.
To create a webhook:
- Go to Definitions > Webhooks from the left menu on your Orkes Conductor cluster.
- Select + New Webhook.
- Enter the following details:
| Parameter | Description |
|---|---|
| Webhook name | A unique name for the webhook. |
| Workflow to receive webhook event | The workflow that must receive the incoming webhook event—this is the one you created in Step 1. If the webhook is intended to start a new workflow, leave this field blank. |
| Source platform | The platform from which this webhook event will be invoked. Supported platforms:
|
| Start workflow when webhook events come | Enable this option to automatically start a workflow using the data received from the webhook event. Once enabled, you must specify the workflow name, version, and (optionally) an idempotency key. The event payload will be passed as input to the specified workflow. |
When both the options—Workflow to receive webhook event and Start workflow when webhook events come—are configured, the webhook payload will be sent to both workflows.
- Select Save.
An unverified webhook URL will be generated.
Here is the JSON schema for a webhook:
{
"verifier": "HEADER_BASED",
"secretValue": "***",
"headers": {
"appName": "demoApp"
},
"name": "webhook-name",
"id": "7a308c91-4189-4e34-8ddb-347cbbfd82fe",
"receiverWorkflowNamesToVersions": {
"sample-webhook": 1
},
"workflowsToStart": {
"start-http-task": 2
},
"urlVerified": true,
"sourcePlatform": "Custom",
"createdBy": "john.doe@acme.com"
}
Step 3: Verify the webhook URL
The next step is to verify the webhook URL. The verification mechanism varies based on the platform from which webhook events will be received. Conductor supports incoming webhooks over HTTPS with the following verification methods:
| Method | Description | Used by | Examples |
|---|---|---|---|
| Header-based verification | A header-based verifier validates incoming requests by checking for headers and their expected values. The request must match all headers and values as specified in Conductor; otherwise, it will be ignored. The URL is marked as verified when the first matching request is received. | Custom | |
| Challenge-based verification | A challenge-based verifier is used when the external system sends a challenge request to which the Conductor server responds to establish trust. The URL is marked as verified once this challenge response is completed. Until then, all incoming requests are ignored. | Slack | |
| Signature-based verification | A signature-based verifier validates the payload signature. This validation requires configuring the secret or header key on the Conductor side. When the request comes, Conductor calculates the request payload hash, and if it matches the pre-configured secret or header value in Conductor, the URL is marked as verified. |
|
Once the URLs are verified (using the respective verification method), the URL status will be marked as Verified.
Step 4: Verify incoming webhooks
The incoming webhook payload triggers the workflow in different ways, depending on your use case:
- If the workflow is waiting for a specific webhook event–After you run the workflow, it pauses at the Wait for Webhook task. When the expected event is received, the workflow continues automatically.
- If the webhook is configured to start a workflow–Conductor can automatically start the workflow when a webhook event is received. The event payload will be passed as input to the specified workflow.
- If both options are configured–When you configure both Workflow to receive webhook event and Start workflow when webhook events come, Conductor sends the webhook payload to both workflows.
To verify that the webhook events have been received by Conductor, open the webhook, by navigating to Definitions > Webhook, and access the webhook execution history.
This includes details such as the event ID, whether the headers are matched, the triggered workflow execution IDs, and the timestamp of when the event was received.