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

• A SpatialFlow account (sign up here)
• An API key or JWT token (see Authentication)
• At least one geofence (see Create Your First Geofence)

Option A — Create via the Dashboard

Navigate to the Workflow Builder

1. Log in to the SpatialFlow Dashboard
2. Click Automations in the top navigation, then select My Automations
3. Click the Create Workflow button
4. The workflow builder opens with a visual canvas, a tabbed component palette on the left (Triggers / Actions / Conditions), and a properties panel on the right

Add a Trigger

1. In the component palette, select the Triggers tab
2. Drag the Geofence trigger node onto the canvas
3. Click the trigger node to open the Node Inspector on the right
4. Configure the trigger:

Field	Value
Trigger Type	Entry (dropdown — choose Entry, Exit, or Dwell)
Geofence	Select the geofence you created in the previous guide

Add an Action

1. Select the Actions tab in the palette
2. Drag a Webhook action node onto the canvas (it appears as "HTTP Request" on the node)
3. Connect the trigger to the action by dragging from the trigger's output handle to the action's input handle
4. Click the action node to configure it in the Node Inspector:

Field	Value
Name	Warehouse Arrival Alert
URL	https://webhook.site/your-unique-url
Method	POST
Headers	Content-Type: application/json
Body	See JSON below

{
  "event": "{{trigger.event_type}}",
  "device": "{{trigger.device.name}}",
  "geofence": "{{trigger.geofence.name}}",
  "location": {
    "lat": "{{trigger.location.lat}}",
    "lng": "{{trigger.location.lng}}"
  },
  "timestamp": "{{trigger.timestamp}}"
}

Template Variables

Workflow actions support template variables that are replaced with real data at execution time. Common variables include {{trigger.device.name}}, {{trigger.geofence.name}}, {{trigger.location.lat}}, {{trigger.location.lng}}, and {{trigger.timestamp}}. See Workflows In Depth for the full list.

Test Your Workflow

1. Click the Test button in the toolbar
2. Review the mock trigger data that is generated
3. Run the test and check the execution log for results
4. Verify that your webhook URL received the request (e.g., check webhook.site)

Save Your Workflow

1. Enter a name for your workflow in the toolbar (e.g., Warehouse Arrival Alert)
2. Click Save — the workflow is saved as a Draft

Draft vs Active

New workflows are saved as Draft and will not trigger from real device events. To activate a workflow, you must first save it, then deploy it from the edit page. See the next step.

Deploy Your Workflow

1. After saving, you are redirected to the edit page for your workflow
2. Click the Deploy button in the toolbar
3. Confirm in the dialog — the workflow status changes to Active

The Deploy button only appears on the edit page (after the initial save), not on the new workflow page.

Option B — Create via the API

Send the Create Request

curl -X POST https://api.spatialflow.io/api/v1/workflows \
  -H "Authorization: Bearer $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 "Authorization: Bearer $SPATIALFLOW_API_KEY"

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

Verify Your Workflow

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 "Authorization: Bearer $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 like:

{
  "event": "geofence_enter",
  "device": "Delivery Truck 1",
  "geofence": "NYC Warehouse Zone",
  "location": {
    "lat": 40.714,
    "lng": -74.006
  },
  "timestamp": "2025-11-10T12:05:00Z"
}

Visual Testing with Route Tester

Use the Route Tester to simulate a device moving along a route that crosses your geofence. This is an easy way to verify your workflow triggers correctly without sending manual location updates.

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 execution history in the Dashboard under Automations → My Automations 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:

• Workflows In Depth — Triggers, actions, conditions, and advanced patterns
• Webhooks — Delivery, retries, signatures, and authentication
• Route Tester — Simulate device movement along routes
• API Reference — Explore the full API documentation