Webhook settings

A webhook lets another system send an HTTP request that starts a workflow. For example, a request-management system can send a newly created request to an intake workflow. Configure the receiving workflow before connecting the sender.

Open this screen from the saved definition's footer menu. You need permission to edit the definition; see Workflow definition settings if the menu or action is unavailable.

Configure a webhook

Choose a published version when the webhook must keep using tested instructions. Leaving Workflow definition version at Latest workflow definition version follows the latest saved definition, including its draft. That is useful while testing but can change the instructions used by later runs. The selected version must be enabled and valid when it starts.

Open Webhook settings from the saved definition's menu.
Select the version and User to start the workflow as. Use an appropriate account in the owning organization that will remain active and unlocked.
Copy Webhook endpoint into the sending system's webhook configuration.
Set Verification request response only if the sender requires a verification reply. Set Validate the payload to reject requests you do not want to run.
Turn Webhook on, then select Save webhook settings.
Send a small test event from the sending system. Open Workflows and inspect the new run's input and first task before sending real work.

The endpoint accepts requests without a signed-in browser session. Its address is not a substitute for checking the sender. Do not enable an unrestricted production webhook merely because a test request succeeds.

Definition: settings and request checks

Setting	What to enter or check
Webhook on	Enables requests. Turn it off and save to stop later webhook starts.
Workflow definition version	Pin a tested published version or deliberately use Latest.
User to start the workflow as	The active, unlocked user under whose account the webhook starts the workflow.
Verification request response	A JSON object with a `headers` object and optional `body` for the HTTP reply. Use `"headers": {}` when you need no custom headers. This does not validate the event.
Validate the payload	A JavaScript expression that must return `true`. An empty check does not restrict the payload; a false result or evaluation error rejects it.

GET requests perform verification without starting a workflow. In a verification response, ${parameters.challenge} selects a query parameter. This example replies with a synthetic sender's challenge; use it only if that sender expects this shape:

{
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "challenge": "${parameters.challenge}"
  }
}

For a GET verification reply, expressions can use request headers, query parameters, and swf:variables. A POST reply instead has headers, parameters and the string body; do not depend on swf:variables in the POST reply. Reply expressions use the normal ${...} JSONPath or ${jsonata:...} JSONata placeholders, not the JavaScript syntax used by the payload check.

POST requests are checked by Validate the payload before they start a run. The JavaScript context is $: $.headers, $.parameters, $.remoteAddress, $.body, and $['swf:variables']. The body is a string, even when it contains JSON. For a sender whose JSON includes an event field, a format check could be:

JSON.parse($.body).event === 'request.created'

This example checks the event type only. It does not authenticate the sender or verify a signature. Use the sender's documented verification requirements and available expression functions before accepting real events. Do not copy secrets into public examples or share a definition containing sensitive literal values.

Example: check a sender's signature

Some senders sign each request so you can check that its body came from someone holding the same signing key. The following is a fictional scheme, not settings for a particular provider: the sender places a lowercase, 64-character HMAC-SHA256 hex signature in x-example-signature, with no prefix, over the exact text body.

For this scheme, create a private definition variable named webhookSigningKey whose JSON value is the signing-key string agreed with the sender. Do not use an example key for real traffic. Variables can be read by people with access to that configuration; they are not a separate secret vault. Limit access, do not expose the key in Page content or responses, and use a task's credentials control when that task provides one.

For Validate the payload, the existing Swf.hmacSha256Hex(key, data) helper can compare the signature with the raw body:

(() => {
  const key = $['swf:variables'].webhookSigningKey;
  const signature = $.headers['x-example-signature'];
  return typeof key === 'string' && key.trim().length > 0
    && typeof signature === 'string' && /^[0-9a-f]{64}$/.test(signature)
    && signature === Swf.hmacSha256Hex(key, $.body);
})()

Use the exact header name supplied in your request context. Do not parse and re-serialize the body before checking it: whitespace and character encoding can change the signed data. Match your real sender's algorithm, encoding, signature prefix and payload format; do not apply this example unchanged to a different scheme or assume it verifies arbitrary binary payloads.

This example compares signatures with ordinary JavaScript equality; it does not provide a constant-time comparison designed to avoid leaking timing information. It is not a complete security verifier for your sender. Follow the sender's verification requirements before using a webhook for sensitive work.

Test one correct signature, an incorrect or missing signature, a missing key, and a changed body. Only the correct case should create a run. A valid signature does not reject repeated delivery of the same event or make processing it twice safe. Arrange duplicate/replay handling for the business operation separately.

Input: what the workflow receives

An accepted POST starts the selected workflow with headers, parameters and the original string body. For example:

{
  "headers": {
    "content-type": "application/json"
  },
  "parameters": {},
  "body": "{\"event\":\"request.created\",\"requestId\":\"REQ-104\"}"
}

Tasks can select the values through their Input Parameters. Parse the body when you need its JSON fields; do not assume workflow.input.body is already an object.

Output and recovery

The HTTP caller gets the configured reply, or an empty successful reply when no response is configured. A reply is not proof that all workflow tasks completed. Inspect the run in Workflows to see the actual task outcomes.

If no run appears, check Webhook on, the selected version's enabled state, the execution user's active/unlocked status and organization, and the payload check. A rejected check returns an unauthorized response. Correct the request or check, then send a new test. Do not repeatedly send a real business event without considering duplicates.