Skip to main content
Webhooks let an external system trigger a Metal workflow when something happens on its side. Instead of polling, your system makes a single POST to a workflow’s webhook trigger, and Metal starts a run.

​
How workflow webhooks work

Each workflow can be configured with a webhook trigger that exposes a unique URL with a per-workflow slug: 
POST https://api.metal.ai/webhooks/workflows/{slug}
When your system posts to this URL, Metal verifies the request and starts a workflow run with the payload as input.
1

Add a webhook trigger to a workflow

In the Metal app, configure the workflow with a webhook trigger. Metal generates the slug and a shared secret used to verify incoming requests.
2

Call the webhook from your system

POST your event payload to the workflow’s webhook URL.
curl -X POST https://api.metal.ai/webhooks/workflows/your-workflow-slug \
  -H "Content-Type: application/json" \
  -d '{ "companyId": "665f1c2a9b1e4a0012a3b4c5" }'
3

Metal starts a run

The incoming payload becomes the run’s input. Track the resulting run with GET /v1/workflow-runs/{id}.

​
Securing webhook triggers

Workflow webhook triggers are verified using the shared secret configured on the trigger. Keep the slug and secret confidential — anyone who can reach the URL with a valid signature can start a run. Rotate a trigger’s secret with: 
POST /v1/workflows/{id}/trigger/webhook-secret/rotate
Treat webhook URLs and their secrets like credentials. If a slug or secret is exposed, rotate the secret immediately.

​
Choosing between webhooks and the API

Use a webhook trigger

When an external system should start a workflow in response to its own events, without managing API keys.

Use the API

When your code already authenticates with Metal and you want to create runs explicitly with POST /v1/workflows/{id}/runs.
Metal also receives inbound webhooks from connected providers (file storage, CRM, and others) to keep data in sync. Those integrations are configured in the app and don’t require any setup in your own code.