Start runs from other systems
A fire alarm panel, a perimeter system, a ticketing tool or a small script can start your Application on its own: it calls a webhook URL, and the platform starts a run with the data the call carries, for example where the alarm went off.
Before you begin
- A console account with the organization administrator role.
- An Application to start, for example the one from the Quickstart, which
takes
latitudeandlongitude. - A system that can send an HTTP
POSTrequest with a JSON body.
Create the webhook
Add an event trigger
Open Manage›Access & Integrations›Event Triggers, select Add Event Trigger, and set Event type to Webhook.
Field What to enter Name The system that will call it, for example Fire alarm panel. Asset Chosen by Dispatch Rules lets the platform pick a suitable device for each call. Choose a device to always use that one. Application and Skill What to start. Only inside site Limit it to one site: then only a call whose position lies inside the site's area starts a run. Priority How much this alarm matters, 75 by default. It decides whether the run may take over a device that is busy with something less important. Cooldown After the webhook fires, further calls are refused for this many seconds. Copy the URL
Select Create. The console shows the webhook's URL once. Copy it and give it to the people who set up the other system.
The last part of the URL is the secret. The URL is the webhook's only key: anyone who has it can start this Application. Keep it like a password, and only send it over channels you trust.
The trigger is listed with the type Webhook, and Last fired shows when it was last called.
Call it
The other system sends a POST request to the URL with a JSON object. Each field of the object
becomes an input of the run, so the alarm's position reaches your Skill:
curl -X POST 'https://<your-console>/api/admin-console/event-triggers/webhook/<secret>' \
-H 'Content-Type: application/json' \
-d '{"latitude": 52.5230, "longitude": 13.4060}'
Include every input the Application requires, named exactly as in the Application. A call without a body sends no inputs.
| Response | Meaning |
|---|---|
| 204 | Accepted. The run starts. |
| 429 Webhook is cooling down | The webhook fired less than Cooldown seconds ago. Nothing new starts. |
| 404 No such webhook | The URL is wrong, the secret was rotated, the trigger was deleted, or it is switched off. |
| 400 | The body is not a JSON object. |
The run appears in Build›Executions like any other, and the drone flies to the position the call sent.
A webhook limited to a site answers 204 to every valid call, but only starts a run when the
call's latitude and longitude lie inside the site's area. That way an alarm system doesn't
keep repeating an event that belongs to another site.
What you have now
- A URL that starts your Application from any system that can make an HTTP request.
- Runs that receive the event's own data as their inputs.
Keep it safe
- Rotate the secret if the URL may have been seen by someone who shouldn't have it: select the rotate button on the trigger's row. The old URL stops working at once, and the new one is shown once. Give it to the other system.
- Switch it off with Active in the trigger's settings to stop it for a while. Calls then get 404.
- Delete the trigger when the other system no longer needs it.
Troubleshooting
- The call gets 404. Check the URL character by character, and that the trigger is active. After a rotation, only the new URL works.
- The call gets 429. The cooldown is running. Lower Cooldown if the other system may legitimately call more often.
- The call gets 204 but no run appears. The webhook is limited to a site and the call's
position is outside it, or carries no
latitudeandlongitude. - The run fails right away. Open it in Build›Executions; the reason is shown on the run. A common one is a target too far for the chosen drone's battery.