Wait For 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. Conductor currently supports Webhook integration with the following third-party systems only:

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

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

Definitions

    {
      "name": "webhook_task",
      "taskReferenceName": "webhook_task_ref",
      "inputParameters": {
        "matches": {
          "$['event']['text']": "$.{workflow.input.somevalue}"
        }
      },
      "type": "WAIT_FOR_WEBHOOK"
    }

Input Parameters

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 a 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 match the webhook event payload where the event.type is message AND event.text is hello.

JSON Example

   {
     "name": "webhook_task",
     "taskReferenceName": "webhook_task_ref",
     "inputParameters": {
       "matches": {
         "$['event']['text']": "$.{workflow.input.somevalue}"
       }
     },
     "type": "WAIT_FOR_WEBHOOK"
   }

Creating Webhook

Let’s create a Webhook now.

1. Navigate to Definitions > Webhooks from the left menu of your Conductor console.
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 the Create button, and the Conductor will generate a Webhook URL, which will be unverified.

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.

The generated URL is to be copied to the platform from which the Webhook will be invoked. The URL status will be Unverified now.

Once the URL is verified based on the verification method, this is what a Webhook with a verified URL looks like.

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.

Different Types of Webhook

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.

So here, the URL is marked as verified when the first Webhook event comes with all the header keys and values configured.

Example - Incoming Webhook using cURL

Example - Incoming Webhook using Postman

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. The Conductor would automatically accept the subsequent requests.
• The URL is marked as verified when the challenge request comes from the system. 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.

Slack Example - Standup Bot using Orkes Conductor

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.

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