Webhook Integration

TrackLab's automation engine can react to system events in real time — measurements arriving from collectors, device parameters changing, weather thresholds being crossed, or external systems posting data via inbound webhooks. When an automation rule matches, it can execute actions such as sending notifications (including outbound webhook calls), setting device parameters, or transitioning lifecycle statuses.

This guide covers the two webhook-related surfaces:

• Inbound webhook sources — endpoints you create so external systems can push data into TrackLab and trigger automation rules.
• Outbound webhook notifications — HTTP calls TrackLab makes to your system when an automation rule fires a "send notification" action configured with a webhook channel.

Creating an inbound webhook source

Inbound webhook sources are scoped to a company and optionally to a specific farm. They allow external systems to post JSON payloads into TrackLab, which are then processed as automation events.

To create a source:

1. Navigate to Automation > Webhooks.
2. Click Add Webhook Source.
3. Enter a name for the source.
4. Optionally select a farm to scope incoming events to that farm.
5. Click Save.

On creation, TrackLab generates:

• An ingest endpoint URL — the URL your external system will POST to.
• A shared secret (64 random characters) — used to authenticate requests.

The secret is shown only once at creation time. Copy it immediately and store it securely.

Ingest endpoint format

POST /api/v1/c/{companySlug}/automation/webhook-sources/{sourceUuid}/ingest

Rotating a secret

If a secret is compromised, rotate it:

1. Find the webhook source in the list.
2. Click the actions menu and select Rotate Secret.
3. Confirm the action.

The old secret is invalidated immediately. Update your external system with the new secret right away — any requests using the old secret will be rejected.

Deleting a source

Deleting a webhook source disables its ingest endpoint permanently. Any automation rules that reference events from this source will no longer receive new events from it.

Event sources

TrackLab's automation engine processes events from several source types. Each source type represents a different category of data entering the system.

Source type	Slug	Description
Measurement	measurement	A collector reports a new measurement value (e.g., angle, current, voltage).
Parameter	parameter	A device parameter value changes (e.g., configuration setting updated).
Weather observed	weather-observed	An observed weather metric is recorded at a farm (e.g., current wind speed).
Weather forecast	weather-forecast	A forecasted weather metric is received for a farm.
Manual API	manual-api	An event fired manually via the API or the automation testing UI.
Inbound webhook	inbound-webhook	An external system posts data to a TrackLab webhook source endpoint.
Data silence	data-silence	A collector has not sent measurements within the configured threshold.

Trigger subject types

When creating an automation rule, you choose a trigger subject type that determines what kind of value the rule evaluates:

Trigger subject	Slug	Description
Measurement value	measurement-value	Evaluate against a numeric measurement from a collector.
Parameter value	parameter-value	Evaluate against a device parameter value.
Weather metric	weather-metric	Evaluate against a weather metric (observed or forecast).
Manual event	manual-event	Trigger on a manually fired event.
Webhook event	webhook-event	Trigger on an inbound webhook payload.

Condition operators

Conditions within a rule's trigger use operators to compare the actual value against a threshold. Conditions can be grouped with and / or logic.

Numeric operators

Operator	Slug	Description
Greater than	gt	Actual value is above the threshold.
Greater than or equal	gte	Actual value is at or above the threshold.
Less than	lt	Actual value is below the threshold.
Less than or equal	lte	Actual value is at or below the threshold.
Equal	eq	Actual value equals threshold (floating-point safe).
Not equal	neq	Actual value does not equal threshold.
Between	between	Actual value falls within a min/max range (inclusive).

String operators

Operator	Slug	Description
Equal	eq	Exact string match.
Not equal	neq	Strings are not identical.
Contains	contains	Actual value contains the threshold substring.
Regex	regex	Actual value matches the threshold regular expression.

Weather metrics

When the trigger subject is weather-metric, the following metrics are available:

Metric	Slug
Wind speed	wind-speed
Wind gust	wind-gust
Temperature	temperature
Humidity	humidity
Rainfall	rainfall

Action types

When a rule's conditions match, one or more actions execute. The available action types are:

Action	Slug	Description
Send notification	send-notification	Dispatch a notification via a configured channel (email, push, or webhook).
Set parameter	set-parameter	Write a new value to a device parameter on the target collector.
Set parameter (broadcast to NCU children)	set-parameter-broadcast-ncu-children	Write a parameter value to all child devices of an NCU.
Transition lifecycle status	transition-lifecycle-status	Move a collector to a different lifecycle status.

Action targets

Actions can be scoped to different target levels:

Target	Slug
Collector	collector
Device group	device-group
Farm	farm
NCU	ncu
NCU children	ncu-children

Failure modes

Each action can be configured with a failure mode:

Mode	Slug	Behavior
Continue on failure	continue-on-failure	If this action fails, subsequent actions still execute.
Stop on failure	stop-on-failure	If this action fails, remaining actions in the rule are skipped.

Authentication and security

Shared secret authentication

Both inbound webhook sources and test webhook endpoints use shared-secret authentication via the X-TrackLab-Webhook-Secret header.

When sending a request to a TrackLab ingest endpoint, include the secret as a header:

X-TrackLab-Webhook-Secret: <your-secret>

TrackLab hashes the provided secret with SHA-256 and compares it against the stored hash using a timing-safe comparison. If the secret is missing or invalid, the request is rejected with a 401 Unauthorized response.

Security recommendations

• Store secrets securely. Use environment variables or a secrets manager — never hard-code them.
• Rotate secrets periodically or immediately if you suspect compromise.
• Use HTTPS. All TrackLab API endpoints require TLS.

Inbound webhook payload format

When an external system posts to an inbound webhook source, TrackLab wraps the payload and dispatches it as an automation event.

Request format

Send a JSON POST request to the ingest endpoint:

curl -X POST \
  'https://app.tracklabsolar.com/api/v1/c/{companySlug}/automation/webhook-sources/{sourceUuid}/ingest' \
  -H 'Content-Type: application/json' \
  -H 'X-TrackLab-Webhook-Secret: <your-secret>' \
  -d '{"sensorId": "WS-001", "windSpeed": 45.2, "unit": "km/h"}'

Stored event payload

The automation event stores the data in this structure:

{
  "webhook_source": "My Weather Station",
  "webhook_source_uuid": "a1b2c3d4-...",
  "payload": {
    "sensorId": "WS-001",
    "windSpeed": 45.2,
    "unit": "km/h"
  }
}

The payload field contains exactly what your external system sent. The webhook_source and webhook_source_uuid fields are added automatically from the webhook source configuration.

Response

A successful ingest returns 202 Accepted:

{
  "success": true,
  "data": {
    "eventDispatched": true
  }
}

The event is dispatched to a background job for processing. Automation rules that match the event will execute asynchronously.

Rule configuration

An automation rule ties together a trigger, conditions, and actions. Key configuration options include:

Field	Description
Name	Human-readable rule name.
Status	enabled, disabled, or paused.
Cooldown minutes	Minimum time between consecutive executions of this rule. Prevents a noisy event from flooding actions.
Auto-clear	Whether the rule automatically clears after a configurable period.
Clear after seconds	How long before the rule auto-clears (when auto-clear is enabled).
Evaluation period seconds	Time window over which events are evaluated.
Evaluation count threshold	Number of matching events required within the evaluation period before the rule fires.

Match suppression

When a rule matches, it can be suppressed:

Status	Slug	Meaning
Matched	matched	Rule matched and actions executed.
Suppressed (cooldown)	suppressed-cooldown	Rule matched but was within the cooldown period.
Suppressed (threshold)	suppressed-threshold	Rule matched but the evaluation count threshold was not met.
Failed	failed	Rule matching failed due to an error.

Testing

The automation testing tab provides tools to validate rules before they go live.

Fire test event

Dispatch a synthetic event into the automation engine to see which rules match and what actions would execute.

Dry-run match

Test a rule's condition logic against a sample value without actually executing any actions. This is useful for verifying that your condition operators and thresholds are configured correctly.

Preview template

Render a notification template with sample data to see the output before it is sent.

Send test notification

Dispatch a real notification through a configured channel to verify delivery.

Webhook test inbox

The webhook test inbox lets you capture and inspect outbound webhook deliveries without needing an external endpoint.

1. Create a test webhook endpoint from the Testing tab (or use the one-step setup endpoint).
2. Configure a notification channel's webhook to point at the test inbox ingest URL.
3. Fire a test event or trigger a rule.
4. Inspect the captured request in the inbox — headers, payload, query parameters, and raw body are all recorded.

The test inbox uses the same X-TrackLab-Webhook-Secret authentication as production webhook sources. Secrets for test endpoints can also be rotated independently.

Example: wind alert webhook

This example walks through setting up an automation rule that sends a webhook notification when observed wind speed exceeds a threshold.

1. Create a notification channel

Set up a webhook notification channel pointing at your external system:

• Channel type: Webhook
• Webhook URL: https://your-system.example.com/alerts
• Headers: Add X-TrackLab-Webhook-Secret with a shared secret, plus any other headers your system requires.

2. Create a notification policy

Link the channel to a notification template:

• Channel: The webhook channel from step 1.
• Template: A template that formats the alert message (e.g., including the metric value and farm name).

3. Create the automation rule

• Name: "High wind alert"
• Status: Enabled
• Cooldown: 5 minutes (prevents repeated alerts for sustained wind)
• Scope: Select the farm(s) to monitor.

4. Configure the trigger

• Subject type: Weather metric (weather-metric)
• Metric: Wind speed (wind-speed)

5. Add a condition

• Operator: Greater than (gt)
• Threshold: 40 (km/h, or whatever unit your weather station reports)

6. Add the action

• Action type: Send notification (send-notification)
• Notification policy: The policy from step 2.

7. Test it

Use Fire Test Event or Dry-Run Match from the Testing tab to verify the rule matches and the notification reaches your endpoint. Use the Webhook Test Inbox to capture the outbound call if you want to inspect the payload before pointing at your production system.