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 platforms:

• GitHub
• Microsoft Teams
• SendGrid
• Slack
• Stripe

You can leverage the Custom option to integrate other than the above-mentioned third-party systems.

Definitions

   {
     "name": "webhook",
     "taskReferenceName": "webhook_ref",
     "inputParameters": {
       "matches": {
         "$['event']['type']": "message",
         "$['event']['text']": "Hello"
       }
     },
     "type": "WAIT_FOR_WEBHOOK"
   }

Input Parameters

Writing Custom Matches

In the above example, you can see that the first part of 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.

Examples

UI

1. Add task type Wait for Webhook.
2. Configure input parameters.

JSON

   {
     "name": "webhook",
     "taskReferenceName": "webhook_ref",
     "inputParameters": {
       "matches": {
         "$['event']['type']": "message",
         "$['event']['text']": "Hello"
       }
     },
     "type": "WAIT_FOR_WEBHOOK"
   }

If your workflow needs to wait for a Webhook, you need to create a Webhook in Orkes Conductor.

Creating Webhook

Steps to create a Webhook in Orkes Conductor:

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:

Attribute	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 will be invoked. The currently supported platforms are GitHub, Slack, Stripe, Microsoft Teams, SendGrid, and 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, version and idempotency key.

4. Click the Save 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 using the verification method, the Webhook URL is verified as shown below:

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. When the request comes, the Conductor calculates the request payload hash and matches 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.

1. Header-based Verifier Webhook

Each request must contain all the headers with the keys and values specified for this type of Webhook. If the keys and values are not specified, the request will be ignored.

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

Check out the following examples implementing header-based Webhook verification.

• Incoming Webhook using cURL

• 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.
• When the system receives a challenge request, the URL is marked as verified. If the URL is not verified, all requests will be ignored until the URL verification is completed via the challenge mechanism. The system that supports the challenge-based verifier is Slack.

Check out the following examples of implementing challenge-based Webhook verification.

• Slack Example - Standup Bot using Orkes Conductor
• Slack Example - Automating Slack Community Greetings

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 request's signature. The systems that support signature-based verifiers are GitHub and Stripe.

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.
Stripe	Header Stripe-Signature will be used to request verification. Endpoint Secret - Provide the endpoint’s secret for Webhook from Stripe.
Microsoft Teams	Header hmac base64-encoded-signature will be used to request verification. Security token - Provide the security token from Microsoft Teams.
SendGrid	Header X-Twilio-Email-Event-Webhook-Signature will be used to request verification. Verification key - Provide the Sendgrid Webhook’s verification key.

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.