Webhook Trigger: Launching Workflows from External Systems via API

What it is

The Workflows Webhook trigger (labeled On Webhook Call in the Start node settings) gives every workflow a unique HTTP endpoint — a URL that any external system can call to start a new workflow instance. When an authorized system sends an HTTP request to that URL with the expected data, a new workflow run begins immediately and the submitted data is available as workflow variables throughout the process.

This lets you connect your existing business systems — ERP platforms, HR systems, contract management tools, helpdesk software, custom scripts, or any software that can send an HTTP request — to your Workflows processes without writing integration code inside the platform.

Why it's useful / Key benefits

• Launch workflows from any system that sends HTTP requests. ERP triggers, email automations, ticketing systems, scheduled scripts, and third-party integrations can all start Workflows processes by calling a URL — no platform login required.
• Every workflow gets its own dedicated URL. There is no shared API key that affects all workflows. Each webhook URL is specific to one workflow and carries only the data for that process.
• Incoming data becomes workflow variables instantly. Fields you define in the payload schema become named workflow variables — available in Task descriptions, Email nodes, conditions, and every downstream node without any mapping step.
• Multiple authentication options. Choose from no authentication, Bearer Token, API Key, or Basic Auth depending on what your external system supports.
• Built-in test tool. Send a test request directly from the designer without leaving the browser to confirm the endpoint is reachable and data is received correctly.
• Workflows started by webhook run just as reliably as manually triggered ones. Once started, the instance runs for as long as the process takes — minutes, days, or weeks — and resumes exactly where it stopped even if the server is restarted. No data is lost.

Before you start

• Administrator role required to configure the Webhook trigger.
• The workflow must be saved (not just open in the designer) with a name before the endpoint URL is generated. Untitled or unsaved workflows show a placeholder URL.
• For external systems to call the webhook, they must have network access to your RAPTIX domain (https://<workspace>.raptix.app).
• To use authentication (Bearer Token, API Key, or Basic Auth), you will need to generate or agree on the credentials with the team that owns the external system.

How to use it — step by step

Step 1 — Open the Start node and select the Webhook trigger

1. Open the workflow in the Visual Designer by selecting the pencil action on its row in Workflow Management.

2. Double-click the Start node (the gold play icon at the top of the canvas). The trigger selection panel opens.

3. In the list of trigger types, click On Webhook Call. The panel expands to show webhook settings.

Step 2 — Review and copy the endpoint URL

The endpoint is automatically generated from the workflow name. It is displayed in the Endpoint field as a read-only value.

4. The field shows a path like /api/v1/dynamic-workflow/http-start/your-workflow-name.

5. Below the field, the full URL is shown in blue:
   https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name

6. Click Copy (the clipboard icon to the right of the field) to copy the full URL to your clipboard.

Important: If the workflow name changes, the endpoint URL changes. Update any external systems that store the URL whenever you rename the workflow.

Step 3 — Configure authentication

7. From the Authentication dropdown, choose how the external system will identify itself:

   Option	What it means
   None	Any caller can start the workflow — no credential required. Use only on internal, firewalled networks or for development.
   Bearer Token	The caller must include Authorization: Bearer <token> in the request header. Suitable for most modern integrations.
   API Key	The caller must include an API Key header. The key name and value are agreed between you and the calling system.
   Basic Auth	The caller must include Authorization: Basic <base64(username:password)> in the header.

8. Choose the method that matches what your external system supports.

Step 4 — Set the HTTP method

9. From the Method dropdown, choose the HTTP method your external system uses to send the request:

   Method	When to use
   POST	Recommended for most integrations. Sends data in the request body.
   GET	Use only when the caller cannot send a body (rare). Data comes from query parameters only.
   PUT	Same as POST but semantically indicates updating an existing resource.
   DELETE	Rarely used for workflow triggers.

   For most integrations, leave this as POST.

Step 5 — Define custom headers (optional)

10. If your external system must include specific headers (for example, a custom X-Source-System header for routing or auditing), click + Add Header.

11. Enter the Header name in the first field and the Header value in the second field.

12. Add as many headers as needed. Click the red X on a row to remove it.

Step 6 — Define the expected payload (JSON Schema)

The Expected Payload field is where you describe the JSON data the external system will send. Each top-level field you define becomes a workflow variable that downstream nodes can use.

13. In the Expected Payload (JSON Schema) textarea, enter a JSON object describing your fields in the format:

    {
      "employee_id": "string",
      "department": "string",
      "request_type": "string",
      "amount": "number",
      "description": "string",
      "submission_date": "date"
    }
    

    Supported types: string, number, boolean, date, array, object.

14. As you type, the field detects the schema and a badge appears showing "N variables detected".

15. Click Preview Variables to see the full list of workflow variables that will be created from this schema. Each field name is prefixed with httpstart_ to create its variable name:

    Field in payload	Workflow variable name
    employee_id	{{httpstart_employee_id}}
    department	{{httpstart_department}}
    amount	{{httpstart_amount}}

16. Note the generated variable names — you will use them in other nodes. For example:

    • In an Email node subject: New request from {{httpstart_employee_id}}
    • In a Task node description: Amount: {{httpstart_amount}}
    • In an If/Else condition: httpstart_amount > 10000

Step 7 — Test the endpoint

17. Click the Test Now button (the green "Test Now" link in the "Test Endpoint" section). The designer sends a test POST request to the endpoint using either your defined payload schema or a default test payload.

18. A popup appears showing the result:

    • Test Successful — HTTP 200 with the response body (including the new instance ID). This confirms the endpoint works and the workflow is ready.
    • Test Failed — HTTP error code with the error message. Common causes: the workflow is not yet saved, the name is blank, or the workflow's status is not Active.

19. If the test fails, check: (1) the workflow has been saved and has a name, (2) the workflow status is Active in the Workflow Management screen, (3) you are not behind a network restriction that blocks local API calls.

Step 8 — Save and share the URL

20. Click Save at the bottom of the settings panel. The Start node on the canvas updates to show a green globe icon indicating the Webhook trigger is active.

21. Share the full endpoint URL and the authentication details with the team responsible for the external system. They will integrate it on their side.

22. Once the external system is configured, test an end-to-end run and confirm a new instance appears in All Instances.

Using webhook data in downstream nodes

After saving the trigger with a payload schema, the variables are available throughout the entire workflow. To reference them:

• In any text field, type {{httpstart_ and the variable panel will autocomplete available names.
• In the Variable Panel (click the variable icon in the designer toolbar), scroll to find all httpstart_ variables listed under the Start node.
• In Condition nodes (If/Else), reference them directly in expression fields, e.g.: httpstart_amount greater than 10000.

Calling the webhook from common tools

From cURL (command line)

curl -X POST \
  "https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name" \
  -H "Content-Type: application/json" \
  -H "Authorization: ${RAPTIX_WEBHOOK_AUTH:?set the complete authorization value}" \
  -d '{"employee_id":"EMP-1042","department":"Engineering","amount":15000}'

From a browser (JavaScript fetch)

const response = await fetch(
  'https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-token-here'
    },
    body: JSON.stringify({
      employee_id: 'EMP-1042',
      department: 'Engineering',
      amount: 15000
    })
  }
);
const result = await response.json();
console.log(result.instance_id); // The new workflow instance ID

From Postman

1. Create a new POST request.
2. Set the URL to the full endpoint URL.
3. Under Headers, add Content-Type: application/json and any authentication header.
4. Under Body > raw > JSON, paste your payload.
5. Click Send. A 200 response with instance_id confirms success.

Options & settings explained

Tips & best practices

• Use descriptive field names in your payload schema. Variable names like httpstart_vendor_invoice_number are clearer than httpstart_num when you reference them 10 nodes later.
• Document the payload schema externally. Share the JSON schema with the team building the external integration so they know exactly what to send.
• Validate the workflow name before sharing the URL. The name is part of the URL. A name containing special characters may produce unexpected URL encoding. Use simple alphanumeric names with hyphens.
• Never leave authentication on "None" in production on a public-facing server. At minimum use Bearer Token to prevent unauthorized workflow starts.
• Test a sample payload before going live. Use the designer's "Test Now" button or Postman to confirm the data arrives correctly and the right variables appear in All Instances.
• Keep the workflow Active. A webhook call to an Inactive workflow returns an error. Confirm Active status in Workflow Management before handing off the URL.
• If the workflow name must change, update all callers at the same time. There is no URL redirect — old URLs stop working immediately.

Frequently asked questions

Q: Does the webhook endpoint require a user account to call? No. The endpoint is publicly callable by design so that external systems can call it without logging in. Authentication (Bearer Token, API Key, or Basic Auth) provides security instead. Always use authentication on production endpoints.

Q: What HTTP status codes does the endpoint return?

• 200 OK — Workflow instance created successfully. Body contains instance_id, status, and workflow_name.
• 400 Bad Request — The request body was malformed or missing required fields.
• 404 Not Found — No active workflow exists with that name.
• 405 Method Not Allowed — Wrong HTTP method used.
• 429 Too Many Requests — Request rate limit exceeded.
• 500 Internal Server Error — A server-side error occurred.

Q: How do I handle webhook failures on the calling system's side? Workflows does not automatically retry failed webhook calls — the calling system is responsible for retrying. If you need retry logic, implement it on the caller's side. For monitoring, check All Instances to see if instances are being created as expected.

Q: Can I send nested JSON objects in the payload? Yes. Nested objects in the payload are also parsed and made available as workflow variables. If you define a field as type object, it will be stored as a JSON string variable. You can reference specific nested values using dot notation in condition nodes, depending on the expression builder's capabilities.

Q: What if I need to pass binary data (files)? The webhook endpoint accepts JSON only. For file-based workflows, use a published Trigger Manually form with file fields or collect files at a later Task node.

Q: Can multiple external systems call the same webhook URL? Yes. As long as all callers use the correct URL, payload format, and authentication, each call creates a separate workflow instance. Rate limiting applies across all callers.

Q: Is the incoming request data logged anywhere for audit purposes? Yes. Workflow Database's Actions tab contains persisted workflow action records. The current tab also allows authorised users to add, edit, or delete those records, so use your organisation's approved audit retention process when immutable evidence is required. Workflow instance data is also accessible through the Workflow Detail View.