Skip to main content

Run Workflows via Webhooks

Run your Hatz workflows programmatically from external systems using HTTP webhooks.

Updated this week

HTTP webhook endpoints allow you to trigger Hatz workflows from external applications, services, or systems without manual intervention. Each workflow can generate a unique webhook URL that accepts POST requests, enabling seamless integration with your existing tools and automation pipelines.

Run via Webhook is currently available to Admin users only. This is because triggering a workflow by webhook requires generating an API key, and only Admins can generate API keys at this time.

If you don’t see the “Generate API Keys” option (or you can’t create an API key), you likely don’t have Admin permissions. Please contact your workspace/admin owner to generate an API key for you.

Future availability: This feature will be rolled out to non‑admin users in a future update.

Run a Workflow via Webhook

Prerequisites

  • Access to Hatz Workshop

  • An existing workflow (can be single-step or multi-step)

  • Basic understanding of HTTP POST requests and APIs

  • API keys generated in your Hatz account (required for authentication)

The “Run via Webhook” section gives you a special web address (a Webhook URL) you can call to start this workflow from somewhere else—for example:

  • another app (Zapier/Make/your backend)

  • a script on your computer

  • a tool like Postman

  • a server that wants to trigger this workflow automatically

Think of it like a doorbell:

  • When something “presses the button” (sends a request to the Webhook URL), the workflow runs

What you need before it will work

1) A Webhook URL

You’ll see something like: https://ai.hatz.ai/v1/workflows/run

This is the endpoint you send a request to in order to run the workflow.

2) An API key (a secret password)

The request must include an API key to prove you’re allowed to run it.

In the view, there’s a “Generate API Keys” option. Use that to create an API key, then copy it somewhere safe.

Important: Treat your API key like a password. Don’t paste it into public places or share it widely.

The easiest way to test it: Postman

Postman is a free tool that helps you send test requests.

  1. Open Postman

  2. Create a new request

  3. Set the method to POST

  4. Paste the Webhook URL:
    ​https://ai.hatz.ai/v1/workflows/run

  5. Go to Headers and add:

    • x-api-key = your API key

    • Content-Type = application/json

  6. Go to Body → raw → JSON and paste something like:

{   "app_id": "YOUR_APP_ID",   "inputs": {} }

  1. Click Send

  2. If everything is correct, you should get a response showing the workflow started (or a run/result object).

Running it from a terminal (curl example)

If you’re comfortable using a command line, you can run the workflow with curl like the example shown in the UI:

curl -X POST "https://ai.hatz.ai/v1/workflows/run" \   -H "x-api-key: YOUR_API_KEY" \   -H "Content-Type: application/json" \   -d '{     "app_id": "YOUR_APP_ID",     "inputs": {}   }'

What each part means

  • POST .../workflows/run → “Start a workflow run”

  • x-api-key: ... → your secret key (permission)

  • Content-Type: application/json → you’re sending JSON

  • app_id → which workflow/app to run

  • inputs → the data you want to pass into the workflow (can be empty if your workflow doesn’t require inputs)

What are “inputs”?

Inputs are the values you want to send into the workflow at run time.

Examples of common inputs:

  • a customer’s email address

  • a support ticket ID

  • a text prompt

  • a document URL

If your workflow expects inputs, you’ll put them inside "inputs" like:

{   "app_id": "YOUR_APP_ID",   "inputs": {     "email": "[email protected]",     "ticket_id": "12345",     "message": "Customer is asking about billing."   } }

(Your exact input names depend on how the workflow was built.)

Mapping Inputs (Formatting + How to Match Your Workflow)

If your workflow has input fields (for example, text boxes you fill in when running manually), you can “map” values into those fields by sending them in the inputs object of your webhook request.

1) Use the exact input field names as keys

Inside "inputs", each key must match the workflow input name exactly (including spelling and capitalization).

Example:

{   "app_id": "YOUR_APP_ID",   "inputs": {     "company_name": "Acme Corporation",     "industry": "Technology"   } }

2) Always send inputs as JSON

Your request body must be valid JSON and include:

  • app_id (required)

  • inputs (object; can be {} if your workflow has no inputs)

No inputs required:

{   "app_id": "YOUR_APP_ID",   "inputs": {} }

3) Input value types (what you can put on the right side)

Most workflows accept simple JSON values

Example:

{   "app_id": "YOUR_APP_ID",   "inputs": {     "email": "[email protected]",     "priority": "high",     "send_reply": true,     "ticket_number": 12345   } }

4) cURL formatting tip (to avoid JSON errors)

When using curl, wrap the entire JSON body in single quotes and keep JSON keys/strings in double quotes:

curl -X POST "https://ai.hatz.ai/v1/workflows/run" \   -H "x-api-key: YOUR_API_KEY" \   -H "Content-Type: application/json" \   -d '{     "app_id": "YOUR_APP_ID",     "inputs": {       "company_name": "Acme Corporation",       "industry": "Technology"     }   }'

Common mapping mistakes

  • Wrong key name (doesn’t match the workflow input name) → the workflow may treat it as missing.

  • Missing required inputs → you’ll get an error or the run won’t behave as expected.

  • Invalid JSON (trailing commas, single quotes inside JSON) → 400 Bad Request.

Troubleshooting

  • 401 / Unauthorized / invalid API key
    Your x-api-key is missing, incorrect, or expired. Generate/copy a valid key and try again.

  • 400 / Bad Request
    Your JSON is invalid (missing quotes, extra commas) or required fields like app_id are missing.

  • Nothing happens / unexpected result
    The workflow may require specific inputs. Confirm the required input fields and try again with those included.

How to Set Up Webhook Triggers

Step 1: Access the Workflow

  1. Navigate to Workshop in the left sidebar

  2. Open the workflow you want to trigger via HTTP

  3. Locate the Run via Webhook panel in your workflow settings

Step 2: Get Your Webhook URL

The webhook panel displays:

  • Webhook URL: A unique endpoint for your workflow

    • Format: https://ai.hatz.ai/v1/workflows/run

    • This is the URL you'll POST to when triggering the workflow

Step 3: Generate API Keys

  1. Click Generate API Keys in the webhook panel

  2. Store your API key securely - you'll need it for authentication

  3. Never share your API key publicly

Step 4: Make HTTP POST Requests

Use the provided cURL example as a template:

curl -X POST "https://ai.hatz.ai/v1/workflows/run" \   -H "x-api-key: <your-api-key>" \   -H "Content-Type: application/json" \   -d '{     "app_id": "2cfc529e-6fd9-4a82-8f27-87b6f395c930",     "inputs": {}   }'

Required Headers:

  • x-api-key: Your Hatz API key for authentication

  • Content-Type: Must be application/json

Request Body Parameters:

  • app_id: The unique identifier for your workflow (found in the webhook panel)

  • inputs: An object containing the workflow's input values

Passing Inputs to Your Workflow

If your workflow includes user inputs (red fields in the workflow builder), you must pass them in the inputs object.

Example with Inputs

For a workflow with inputs like "company_name" and "industry":

{   "app_id": "2cfc529e-6fd9-4a82-8f27-87b6f395c930",   "inputs": {     "company_name": "Acme Corporation",     "industry": "Technology"   } }

Example without Inputs

If your workflow has no user inputs or uses only constant files:

{   "app_id": "2cfc529e-6fd9-4a82-8f27-87b6f395c930",   "inputs": {} }

Expected Results

When successfully triggered:

  • The workflow executes immediately with the provided inputs

  • The workflow runs with the same configuration as manual runs

  • You can view the run in your Workflow Run History

  • Credits are consumed from your account just as with manual runs

Troubleshooting

Please note: While the Hatz AI Support and Experience teams can help with basic troubleshooting (e.g., verifying your webhook URL and API key), we do not provide full API implementation support. For advanced help—such as building custom integrations, writing/debugging code, configuring authentication in your systems, or diagnosing issues in third‑party tools—please work with your engineering team or a technical integration partner.

Error: Authentication Failed

  • Verify your API key is correct and included in the x-api-key header

  • Regenerate your API key if needed

Error: Invalid app_id

  • Double-check the app_id matches your workflow exactly

  • Copy the app_id directly from the webhook panel

Error: Missing Required Inputs

  • Ensure all required workflow inputs are included in the inputs object

  • Check that input field names match exactly (case-sensitive)

Workflow Not Running

  • Confirm the workflow is saved and published

  • Check your account has sufficient credits

  • Review the Workflow Run History for error details

Limitations

  • API keys are account-specific and cannot be shared between users

  • Each workflow has one unique webhook URL that cannot be customized

  • Webhook calls count against your credit usage the same as manual runs

  • Webhook responses do not return workflow outputs directly - you must check Run History to view results

  • The webhook URL format and authentication method cannot be modified

  • Inputs must be provided as JSON - other formats are not supported

  • Nested or complex input structures may have limitations depending on your workflow configuration

Security Best Practices

  • Store API keys securely using environment variables or secrets management

  • Never expose API keys in client-side code or public repositories

  • Regenerate API keys immediately if compromised

  • Limit API key access to only the services that need it

Did this answer your question?