Skip to main content

Create Your First Workflow

Learn how to build a workflow that triggers an action when a device enters a geofence. This guide covers both the SpatialFlow Dashboard and the API. For a deeper look at triggers, actions, and advanced options, see Workflows In Depth.

Prerequisites​

Creating a workflow from the dashboard​

If you'd rather build a workflow visually than call the API, see Alerts and workflows in the manager guides. It covers the trigger and action palette, template variables, and the save, test and deploy steps. Every new workflow starts as a Draft and won't fire until you deploy it.

Create via the API​

Send the Create Request​

curl -X POST https://api.spatialflow.io/api/v1/workflows \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Arrival Alert",
    "description": "Send a webhook when a truck enters the warehouse zone",
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "data": {
          "triggerType": "geofence_enter",
          "label": "Geofence Entry",
          "config": {
            "geofence_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
          }
        }
      },
      {
        "id": "action-1",
        "type": "action",
        "data": {
          "actionType": "webhook",
          "label": "HTTP Request",
          "config": {
            "url": "https://webhook.site/your-unique-url",
            "method": "POST",
            "headers": {
              "Content-Type": "application/json"
            },
            "body": {
              "device": "{{trigger.device_name}}",
              "geofence": "{{trigger.geofence_name}}",
              "timestamp": "{{trigger.timestamp}}"
            }
          }
        }
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "trigger-1",
        "target": "action-1"
      }
    ]
  }'

Replace the geofence_ids UUID with the geofence ID returned when you created your first geofence.

Review the Response​

A successful 201 Created response returns the workflow object:

{
  "id": "f8a1b2c3-d4e5-6789-abcd-ef0123456789",
  "name": "Warehouse Arrival Alert",
  "description": "Send a webhook when a truck enters the warehouse zone",
  "status": "draft",
  "version": 1,
  "nodes": [ ... ],
  "edges": [ ... ],
  "run_count": 0,
  "success_rate": 0.0,
  "last_run": null,
  "user_id": "usr_abc123",
  "created_at": "2025-11-10T12:00:00Z",
  "updated_at": "2025-11-10T12:00:00Z"
}

Save the id; you'll need it to activate and test the workflow.

Activate the Workflow​

New workflows are created in draft status. Activate it with:

curl -X POST https://api.spatialflow.io/api/v1/workflows/f8a1b2c3-d4e5-6789-abcd-ef0123456789/activate \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY"

The response returns the updated workflow with "status": "active".

Verify Your Workflow​

Before sending location updates, the device must have an active shift. Start one with:

curl -X POST https://api.spatialflow.io/api/v1/devices/YOUR_DEVICE_UUID/start-shift \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY"

Then send a device location inside your geofence to trigger the workflow:

curl -X POST https://api.spatialflow.io/api/v1/devices/YOUR_DEVICE_UUID/location \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 40.714,
    "longitude": -74.006
  }'

Replace the coordinates with a point inside your geofence and YOUR_DEVICE_UUID with your device's UUID.

Check your webhook URL. You should receive a payload matching the body template you defined in the action config, with template variables resolved:

{
  "device": "Delivery Truck 1",
  "geofence": "NYC Warehouse Zone",
  "timestamp": "2025-11-10T12:05:00Z"
}
Workflow Not Triggering?

If your workflow doesn't fire, check the following:

  1. Verify the workflow status is Active (not Draft or Paused)
  2. Confirm the geofence used in the trigger matches the one the device entered
  3. Make sure the device is sending location updates to SpatialFlow
  4. Review the workflow's Runs page for error details

You've successfully created and activated your first workflow:

  • Built a workflow with a geofence trigger and webhook action
  • Deployed the workflow to start processing real events
  • Verified the workflow fires when a device enters the geofence

Next Steps​

Ready to explore more? Continue with these guides: