Create Webhook

Endpoint: POST /api/metadata/webhook

Creates a new webhook definition.

Request body

Format the request body as an array with the following parameters:

Paramaeter	Description	Type	Required
name	The name of the webhook.	string	Required.
receiverWorkflowNamesToVersions	Map of workflow names to versions that receive the incoming webhook event. If the webhook is only used to start a workflow, this object can be empty. For example: "receiverWorkflowNamesToVersions": { "<WORKFLOW-NAME>": <WORKFLOW-VERSION> }	object	Optional.
sourcePlatform	The platform that sends webhook requests to Conductor. Supported values: Github Microsoft Teams SendGrid Slack Stripe Custom This value determines the verification method and the security fields required for the webhook.	string	Required.
verifier	The verification method used to validate incoming webhook requests. Supported values: SIGNATURE_BASED: For GitHub HMAC_BASED: For Microsoft Teams SENDGRID : For SendGrid SLACK_BASED: For Slack STRIPE: For Stripe HEADER_BASED: For Custom	string	Required.
headerKey	The header key used to verify incoming webhook requests. Supported values: X-Hub-Signature-256: For GitHub Authorization: For Microsoft Teams Stripe-Signature: For Stripe	string	Required for GitHub, Microsoft Teams, and Stripe. Not applicable for other platforms.
secretValue	The secret value used to verify incoming webhook requests. Supported platforms: GitHub: Enter an arbitrary Secret key. You’ll reuse this same value when you configure the webhook in GitHub. Microsoft Teams: Leave the Security token empty for now. This can be added once you get the security token from Microsoft Teams webhook. SendGrid: Leave the Verification key empty for now. This can be added once you get the verification key from SendGrid webhook. Stripe: Leave the Endpoint secret empty for now. This can be added once you get the endpoint secret from Stripe webhook.	string	Required for GitHub, Microsoft Teams, SendGrid, and Stripe. Not applicable for other platforms.
headers	The key-value pairs of headers used to validate incoming webhook requests.	object	Required for Custom.
workflowsToStart	Map of workflows configured to start when the webhook event is received. For example: "workflowsToStart": { "<WORKFLOW-NAME>": <WORKFLOW-VERSION> }	object	Optional.
workflowsToStart.idempotencyKey	The idempotency key to prevent duplicate workflow executions for the same webhook event. Supports variables from the workflow input, for example, ${workflow.input.someKey}.	string	Optional.
workflowsToStart.idempotencyStrategy	The strategy to use when a workflow with the same idempotency key already exists. Supported values: RETURN_EXISTING: Return the workflowId of the workflow instance with the same idempotency key. FAIL: Start a new workflow instance only if there are no workflow executions with the same idempotency key. FAIL_ON_RUNNING: Start a new workflow instance only if there are no RUNNING or PAUSED workflows with the same idempotency key. Completed workflows can run again.	string	Optional.

Response

Returns 200 OK with the created webhook object, including the following system-generated fields:

Parameter	Description
id	The unique identifier of the webhook.
urlVerified	Indicates whether the webhook URL has been verified. Returns true if verified.

Examples

Create a Custom webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-test-webhook",
  "sourcePlatform": "Custom",
  "verifier": "HEADER_BASED",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "workflowsToStart": {
    "idempotencyKey": "${workflow.input.bug_id}",
    "idempotencyStrategy": "RETURN_EXISTING",
    "json-env-example": 1
  },
  "headers": {
    "source": "internal-portal"
  }
}'

Response

{
  "name": "my-test-webhook",
  "id": "d62c2e7f-1b9d-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "workflowsToStart": {
    "idempotencyKey": "${workflow.input.bug_id}",
    "idempotencyStrategy": "RETURN_EXISTING",
    "json-env-example": 1
  },
  "urlVerified": false,
  "sourcePlatform": "Custom",
  "verifier": "HEADER_BASED",
  "headers": {
    "source": "internal-portal"
  },
  "createdBy": "john.doe@acme.com"
}

Create a GitHub webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "GitHubWebhook",
  "sourcePlatform": "Github",
  "verifier": "SIGNATURE_BASED",
"headerKey":"X-Hub-Signature-256",
"secretValue":"123",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  }
}'

Response

{
  "name": "GitHubWebhook",
  "id": "1fe77966-1ba4-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "urlVerified": false,
  "sourcePlatform": "Github",
  "verifier": "SIGNATURE_BASED",
  "headerKey": "X-Hub-Signature-256",
  "secretValue": "123",
  "createdBy": "john.doe@acme.com"
}

Create a Microsoft Teams webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "MicrosoftTeamsWebhook",
  "sourcePlatform": "Microsoft Teams",
  "verifier": "HMAC_BASED",
"headerKey":"Authorization",
"secretValue":"",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  }
}'

Response

{
  "name": "MicrosoftTeamsWebhook",
  "id": "67baca62-1ba4-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "urlVerified": false,
  "sourcePlatform": "Microsoft Teams",
  "verifier": "HMAC_BASED",
  "headerKey": "Authorization",
  "secretValue": "",
  "createdBy": "john.doe@acme.com"
}

Create a SendGrid webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "SendGridWebhook",
  "sourcePlatform": "SendGrid",
  "verifier": "SENDGRID",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  }
}'

Response

{
  "name": "SendGridWebhook",
  "id": "9f16b264-1ba4-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "urlVerified": false,
  "sourcePlatform": "SendGrid",
  "verifier": "SENDGRID",
  "createdBy": "john.doe@acme.com"
}

Create a Slack webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "SlackWebhook",
  "sourcePlatform": "Slack",
  "verifier": "SLACK_BASED",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  }
}'

Response

{
  "name": "SlackWebhook",
  "id": "cb844d4e-1ba4-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "urlVerified": false,
  "sourcePlatform": "Slack",
  "verifier": "SLACK_BASED",
  "createdBy": "john.doe@acme.com"
}

Create a Stripe webhook

Request

curl -X 'POST' \
  'https://<YOUR-SERVER-URL>/api/metadata/webhook' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "StripeWebhook",
  "sourcePlatform": "Stripe",
  "verifier": "STRIPE",
"headerKey":"Stripe-Signature",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  }
}'

Response

{
  "name": "StripeWebhook",
  "id": "ffb50f52-1ba4-11f1-afe6-be25ff45d334",
  "receiverWorkflowNamesToVersions": {
    "http": 1
  },
  "urlVerified": false,
  "sourcePlatform": "Stripe",
  "verifier": "STRIPE",
  "headerKey": "Stripe-Signature",
  "createdBy": "john.doe@acme.com"
}

Related pages

• Webhook API
• Update Webhook
• Get Webhook by ID
• Delete Webhook
• Get All Webhooks
• Add Tags to Webhook