Incoming Custom Webhook using Postman

This tutorial demonstrates how to create a custom webhook in Orkes Conductor and trigger it with a Postman request.

In this tutorial, you will:

1. Create a Conductor workflow with a Wait for Webhook task.
2. Set up a custom webhook in Conductor to receive events.
3. Run the workflow.
4. Send a Postman request to trigger the webhook.
5. Verify incoming webhook requests.

To follow along, ensure you have access to the free Orkes Developer Playground.

Step 1: Create a workflow in Conductor

Create a workflow with a Wait for Webhook task to receive webhook events.

To create a workflow:

1. Go to Definitions > Workflows from the left menu on your Conductor cluster.
2. Select + Define workflow.
3. In the Code tab, paste the following code:

{
 "name": "sample-webhook-postman",
 "description": "Sample webhook for demonstration purpose",
 "version": 1,
 "tasks": [
   {
     "name": "webhook_task",
     "taskReferenceName": "webhook_task_ref",
     "inputParameters": {
       "matches": {
         "$['data']['recipientId']": "${workflow.input.recipientId}"
       }
     },
     "type": "WAIT_FOR_WEBHOOK"
   }
 ],
 "inputParameters": [
   "recipientId"
 ],
 "schemaVersion": 2
}

4. Select Save > Confirm.

Your workflow will look like this:

Step 2: Create a webhook in Conductor

Next, create a custom webhook that listens for incoming events from Postman.

To create a webhook:

1. Go to Definitions > Webhook from the left menu on your Conductor cluster.
2. Select + New webhook.
3. In the Code tab, paste the following code:

{
 "verifier": "HEADER_BASED",
 "headers": {
   "appName": "demoApp"
 },
 "name": "SampleWebhookPostman",
 "receiverWorkflowNamesToVersions": {
   "sample-webhook-postman": 1
 },
 "sourcePlatform": "Custom"
}

4. Select Save.

An unverified webhook URL is generated. It remains unverified until a request with the expected headers is received.

Step 3: Run workflow

Before triggering the webhook, run the workflow with an input value that the webhook event should match.

Since the Wait for Webhook task uses the following input matches:

       "matches": {
         "$['data']['recipientId']": "${workflow.input.recipientId}"
       }

Run the workflow to pass recipientId as the workflow input.

Go back to your workflow definition, navigate to the Run tab, and paste the following input parameters:

{
"recipientId":"123"
}

Select Run workflow to view the execution.

The workflow is now running and waiting for a webhook event that contains an input payload with “recipientId”: "123".

Step 4: Send a request using Postman

Now that the workflow is waiting for input, you can send a matching request using Postman.

You ran the workflow using the input:

{
"recipientId":"123"
}

Therefore, send a matching request from Postman.

To configure a Postman request:

1. Log in to Postman.
2. Select Send an API request > New Request.
3. Create a new request with the following configurations:

• Method: POST.
• URL: The unverified webhook URL from Conductor.

4. In the Headers section, add the following key-value pair: appName: demoApp.

5. In the Body tab, select raw and choose JSON. Paste the following payload:

{
  "data": {
    "recipientId": "123"
  }
}

note

Ensure to pass the matching input JSON. The value for "recipientId" in the request payload must match the input provided when running the workflow ("123" in this example).

6. Select Send.

The Postman request should return a 200 OK.

Step 5: Verify incoming webhook requests

Once the request is received, the webhook is automatically verified, and the payload is received in Conductor.

Select the workflow (execution) ID from the Webhook execution history to view the execution. You can verify that the webhook task is completed.

You’ve successfully created and triggered a custom webhook in Orkes Conductor using Postman.