Start a workflow from another system with a webhook

Before you start

• Choose when a workflow runs

A webhookWebhookA workflow trigger by which another system calls a URL.Open glossary ↗ gives a workflow its own web address. When another system calls that address, the workflow runs, and the data in the call is available to its steps. Use it to take in orders from a website, events from a payment system, or anything that can send an HTTP request.

Set up the webhook

1. Open Automation for the module and click New workflow, or open the Settings of an existing one.
2. Under When should it run?, click From a webhook.
3. Switch on Require an API key unless the call comes from a place you fully control.
4. Switch on Send the result back if the other system should hear how the run ended. Fill in the callback settings below.
5. Make sure On is switched on, then click Save.
6. In the list, open the workflow’s three dots and click Copy webhook URL.

○ ○ ○Beezr

×

Require an API key: callers must send your API key in the api-key header.
Send the result back posts the PID, status, duration and error to your address.
The Callback URL must start with http:// or https://.
Shared secret (optional) is sent back to you in a header, so you can check the call is from Beezr.

Copy webhook URL is in the three-dot menu of every webhook workflow.

How does the other system call it?

Send a POST request with a JSON body to the address you copied. If the webhook requires a key, add the api-key header. Create the key under API keys in Account settings. See Create and manage API keys.

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"vendor": "Nile Supplies", "amount": 12500}'

Beezr answers at once with HTTP 202 and the run’s identifier. The workflow runs afterwards, in the background.

{"pid": "7f1c2a9e-0000-4000-8000-000000000000", "status": "ACCEPTED", "message": "Webhook accepted for processing"}

HTTP code	status	Meaning
202	ACCEPTED	The call is queued. Keep the pid
400	REJECTED	Check the address, and that the workflow is on
401	UNAUTHORIZED	A key is required and is missing, wrong or paused
413	PAYLOAD_TOO_LARGE	The body is too large. Send a smaller one
503	UNAVAILABLE	Beezr could not store the call. Try again later

Tip from a Beezr Consultant

Always send a JSON body, even if it is only {}. The workflow starts from the data you send.

How does the workflow read the data?

Add a JSON parser step first. Under Read, keep The data the webhook sent, and describe the shape of the JSON under Its shape. List every field that later steps need.

The run has no signed-in user, and the debugger shows Started by as System. It appears in the debugger like any other run. On a webhook run the debugger adds a Payload tab with the request. Search the PID in the debugger’s search box to find the run that matches a call.

What does the callback send?

When Send the result back is on, Beezr posts the result to your Callback URL after the run ends. Send it decides when.

Option	Posts
When the run fails	Only for failed runs
When the run succeeds	Only for successful runs
Always	After every run

The body is JSON.

{
  "pid": "7f1c2a9e-0000-4000-8000-000000000000",
  "moduleId": 12,
  "moduleName": "Purchase Orders",
  "runDate": "1791963600000",
  "durationMs": 1840,
  "status": "Success",
  "errorMessage": "Success"
}

errorMessage carries the run’s final message. If you set a Shared secret (optional), Beezr sends it in the X-Beezer-Callback-Secret header. Compare it with your copy before you trust the call. Beezr retries delivery and counts any 2xx answer as delivered.

Give each webhook its own key, and the callback its own secret. When one is exposed, you pause that key without touching anything else.