Skip to content

Incoming webhooks

A webhook is an HTTP endpoint that an external service calls when something happens on its side. Conductor verifies the caller's signature first, records the delivery durably, and then either starts a new workflow or resumes one waiting on WAIT_FOR_WEBHOOK. This page covers configuring the endpoint, verification, and both delivery modes.

Incoming webhook processing flow An external provider sends an HTTP callback to an incoming webhook. After verification and durable processing, the configuration can start a workflow, resume a Wait for Webhook task, or do both. ProviderHTTP callback Incoming webhookverify + persistconfigured delivery Start workflow Resume WAITFOR_WEBHOOK

Endpoints and lifecycle

Webhook delivery uses these routes relative to the Conductor API base URL:

Method Route Purpose
POST /webhook/{id} Receive a callback body, query parameters, and headers
GET /webhook/{id} Handle a provider URL-verification or ping request
POST /metadata/webhook Create a webhook configuration
GET /metadata/webhook List configurations
GET /metadata/webhook/{id} Read a configuration
PUT /metadata/webhook/{id} Update a configuration
DELETE /metadata/webhook/{id} Delete a configuration

For example, if the API base URL is https://conductor.example.com/api, give the provider https://conductor.example.com/api/webhook/<webhook-id>.

The inbound request is verified before it is accepted for processing. The recorded event and queue make delivery durable across worker restarts; processing then evaluates the configuration, starts any configured workflows, and matches eligible WAIT_FOR_WEBHOOK tasks. Inspect the webhook/event records and the resulting workflow or task state when diagnosing a delivery.

Choose a delivery mode

Webhook configuration can apply either or both effects to one verified callback:

  • Start: launch each configured receiver workflow.
  • Resume: match and advance eligible WAIT_FOR_WEBHOOK tasks.
  • Both: start the configured workflows and resume matching waits from the same durable callback.

Choose the mode from the state you need to create or advance; a webhook is not an event-handler action dispatcher.

Configure without exposing secrets

The configuration identifies the verifier, optional expected headers, receiver workflow versions or workflows to start, and matching behavior. Keep verifier material in the platform secret store and reference it; never put a signing secret, HMAC key, or private key literal in a workflow or documentation example.

{
  "name": "payment-provider-callback",
  "sourcePlatform": "Custom",
  "verifier": "HMAC_BASED",
  "headerKey": "X-Provider-Signature",
  "secretValue": "${workflow.secrets.PAYMENT_WEBHOOK_SECRET}",
  "receiverWorkflowNamesToVersions": {
    "process_payment_callback": 1
  }
}

Use the secret-reference form supported by your environment rather than copying an actual secret into the configuration. Treat callback payloads and headers as potentially sensitive too.

Verifier choices

Verifier Verification input GET challenge / ping behavior
HEADER_BASED Every configured header must be present exactly once and equal its configured value. No provider challenge behavior.
SIGNATURE_BASED A configured header contains sha256= plus an HMAC-SHA-256 of the raw body using the configured secret. No provider challenge behavior.
HMAC_BASED A configured header carries the HMAC-SHA-256 of the raw body; the configured secret is Base64-decoded before verification. No provider challenge behavior.
SLACK_BASED X-Slack-Signature, X-Slack-Request-Timestamp, and the raw body; the timestamp is replay-window checked. Returns Slack's JSON challenge value during URL verification.
STRIPE Stripe-Signature, raw body, and the Stripe signing secret. No provider challenge behavior.
TWITTER Configured signature header and raw body, using the Twitter HMAC encoding. On crc_token, returns a response_token signed with the configured secret.
SENDGRID SendGrid event-webhook signature and timestamp headers, raw body, and the configured ECDSA public key. No provider challenge behavior.

Verification is a security boundary, not an authorization model for arbitrary workflow actions. Limit each webhook configuration to the workflows and task matches it genuinely needs.

Webhooks versus event handlers

An event handler subscribes to a broker event and can dispatch its documented actions. An incoming webhook receives HTTP and only carries out the webhook configuration's workflow-start and WAIT_FOR_WEBHOOK matching behavior. Do not model a webhook as a way to invoke complete_task, fail_task, terminate_workflow, or update_workflow_variables actions.

For a broker message instead of an HTTP callback, use Consume and route events. To complete the current WAIT in a known workflow directly, use Sending signals to workflows.

Next steps

Route broker events → Signal a WAIT task → Return to the overview →