Integrate Conductor with other systems using Webhook

"type" : "WAIT_FOR_WEBHOOK"

Introduction

This guide details the steps on how to integrate Conductor with other third-party systems using Webhook.

What is a Webhook?

Webhook is an HTTP-based callback function that facilitates the communication between the Conductor and other third-party systems. It can be used to receive data from other applications to the Conductor.

How does Webhook integrate Conductor with other systems?

Webhook enables integration patterns for Conductor workflows, making it possible to build workflows that can act on events occurring outside the Conductor or organization.

Conductor currently supports Webhook integration with the following third-party systems only:

• GitHub
• Slack
• Twilio
• Stripe
• Pagerduty
• Zendesk
• Twitter
• Facebook
• Sendgrid
• Custom

You can leverage the custom option for integrating other than the above-mentioned third-party systems.

Supported Webhook Verification Methods by Conductor

Conductor supports the incoming Webhooks over HTTPS with the following verification methods:

1. Header Verification - Validates a predefined header and value.
2. Signature Verification - Validates the payload signature. This validation requires configuring the secret and header key on the Conductor side. And when the request comes, the Conductor will calculate the request payload hash and match it with the pre-configured header value.
3. Challenge Verification - Used when the third-party system sends a challenge request that the Conductor server responds to establish trust.

Configuring Webhooks in Conductor

Before creating a webhook, ensure that the workflow supposed to receive this Webhook event is already created.

Creating Workflow for the Webhook Event

You can see a sample workflow here. You may have a look at our documentation on creating workflows for detailed steps.

{
 "name": "sample_webhook_for_slack",
 "description": "Sample Webhook for Slack Integration.",
 "version": 1,
 "tasks": [
   {
     "name": "Webhook",
     "taskReferenceName": "Webhook",
     "inputParameters": {
       "matches": {
         "$['event']['type']": "message"
       }
     },
     "type": "WAIT_FOR_WEBHOOK",
   }
 ],
 "inputParameters": [],
 "outputParameters": {},
 "schemaVersion": 2,
 "ownerEmail": "youremail@example.com"
}

A webhook workflow type can be identified as "type": "WAIT_FOR_WEBHOOK" . It is a Conductor task, meaning no worker is required to run the workflow. Also, it is a type of ‘WAIT’ task, where the workflow waits for events from the external systems.

Writing Custom Matches​

In the above example, you can see that the matches are described as follows:

"matches": 
{
    "$['event']['type']": "message"
}

This means that the incoming event payload has JSON path event.type and it must be a message in order to match the webhook event with this task.

You can define any custom JSON path based on the incoming event payload and write matches accordingly.

You can also add multiple matches within the matches. All the matches will be calculated as AND operations within the matches.

"matches": 
{
    "$['event']['type']": "message",
    "$['event']['text']": "hello",
}

For example, the above one will be used to match the webhook event payload where event.type is message AND event.text is hello.

In order to match all the webhook events, the matches should be kept empty.

"matches": 
{
}

Creating Webhook

Now you have created your workflow. Let’s create a Webhook now.

1. Navigate to Webhooks from the Conductor server.
2. Click New Webhook.

   

3. You need to fill in the following details:

Field	Description
Webhook Name	Provide a unique name for your Webhook.
Workflow To Receive Webhook Event	Provide the workflow name that is supposed to receive this webhook event.
Source Platform	Choose the platform from which this webhook event is going to be invoked. The currently supported platforms are GitHub, Slack, Twilio, Stripe, Pagerduty, Zendesk, Twitter, Facebook, Sendgrid & Custom. Note: You can use the option custom for unsupported systems.
Start workflow when webhook events come	Check this option to start a new workflow based on the data received from the webhook event. Once enabled, you need to choose the workflow to be executed.

4. Click Create button, and the Conductor will generate a Webhook URL, which will be unverified.

Different Types of Webhook

Now you’ve seen the basic steps of creating a Webhook. Depending on the Webhook type, you need to configure some additional fields apart from the basic configurations.

1. Header-based Verifier Webhook

For this type of Webhook, each request must contain all the headers with the keys and values specified. The request will be ignored if the keys and values are not specified.

2. Challenge-based Verifier Webhook

For this type of Webhook, the initial invocation must have a challenge parameter and the same will be returned. This way, the Conductor marks the URL as verified. You can view this on the Webhook page. The Conductor would automatically accept the subsequent requests.

If the URL is not verified, then all the requests will be ignored until the URL verification is completed via the challenge mechanism.

The systems that support the challenge-based verifiers are Slack and Facebook.

3. Signature-based Verifier Webhook

This type of Webhook is configured using the token from the source platform. This token is used to verify the signature of the request.

The systems that support the signature-based verifiers are GitHub, Twilio, Stripe, Pagerduty, Zendesk & Twitter.

System	Header for request verification
GitHub	Header X-Hub-Signature 256 will be used to request verification. It is the request body’s HMAC hex digest and is spawned using the SHA-256 hash function and the secret as the HMAC key. secret - Provide the GitHub account’s secret key.
Twilio	Header X-Twilio-Signature will be used to request verification. AuthToken - Provide your AuthToken from the Twilio console.
Stripe	Header Stripe-Signature will be used to request verification. endpointSecret - Provide your endpoint’s secret for Webhook from Stripe.
Pagerduty	Header x-pagerduty-signature will be used to request verification. secret - Provide your Pagerduty’s secret token.
Zendesk	Header X-Zendesk-Webhook-Signature will be used to request verification. SIGNING_SECRET - Provide your Zendesk’s signing secret for Webhook.
Twitter	Header x-twitter-webhooks-signature will be used to request verification. TWITTER_CONSUMER_SECRET - Provide your Twitter app’s consumer secret.

• Click Create button, and the Conductor will generate a Webhook URL. The generated URL is to be copied to the platform from which the Webhook will be invoked. The URL status will be Unverified now.

The process of verifying the URL varies with the Webhook type.

• Header-based verifiers - The URL is marked as verified when the first Webhook event comes with all the header keys and values configured.
• Challenge-based verifiers - The URL is marked as verified when the challenge request comes from the system.
• Signature-based verifiers - The URL is marked as verified when the request comes with the header configured and when the request payload hash in the header and the calculated hash on the Conductor side match.

This is what a Webhook with a verified URL looks like.

Run Workflow

Once the URL is verified, you can run the workflow.

1. From Conductor, click on Run Workflow.
2. Choose your workflow under the field Workflow Name.
3. Click Run Workflow.

4. To check the workflow execution status, click on the generated workflow ID. It would be in the RUNNING state.

5. Complete the requested action from the external system. For example, if the external system is Slack and the action is posting updates to a channel. Open Slack and send the text message to the channel.
6. The workflow executes and the status changes to COMPLETED.

Note: If you have enabled the option to Start workflow when webhook event comes, the event payload will be passed as input to the specified workflow.

Sample Use Case - Sending messages in a Slack channel

Integrating Conductor with other systems using Webhook can be leveraged to cases like creating chatbots, employee onboarding processes, automated scrum updates, automated issue creation on support channel messages, etc.

Now, let’s visualize a sample case where you need to send a message in a Slack channel.

1. Create workflows to send a message in a Slack channel.
2. Create a Slack app that has permission to post to the Slack channel. Then, navigate to Features > Incoming Webhooks, and turn on Activate Incoming Webhooks.

3. Create a webhook that listens for events from Slack. Check the above-mentioned example for creating Webhook.
4. Once the unverified URL is generated, you can use this URL in the Slack app. Under Features > Event Subscriptions, turn on the toggle button Enable Events. Provide the unverified URL of the Webhook under the field Request URL.

5. The URL would now be verified in both the Slack app and the Conductor side.
6. Save the Webhook.
7. Run the workflow. The current status of the workflow will be RUNNING.
8. Open the Slack app and send the text message to the channel.
9. The Workflow is completed now.