Webhooks

The Shoplogix IMS platform offers two distinct webhook systems. Choose the one that matches what you want to receive.

System	What Gets Delivered	API Endpoint
Event Webhooks	Machine alarm state changes, steam trap condition changes	/v2020-07/webhooks
Data Streaming Webhooks	Raw sensor readings, gateway status messages	/ds/v1/webhooks

---

Event Webhooks

Event webhooks fire when high-level equipment state changes occur — a machine enters alarm or a trap's condition changes. These are the best choice for alerting and CMMS work order automation.

Supported Event Types

Event	Trigger
Machine alarm state change	A machine's alarm state transitions (e.g., Good → Alarm)
Steam trap state change	A trap's condition changes (e.g., Good → Unexpected Cold)

Registering an Event Webhook

1. In Shoplogix IMS, go to the Webhooks section (requires the Developer role)
2. Provide your endpoint URL and choose the event types you want to receive
3. Save — you'll receive a signing secret

Or manage via the REST API at /v2020-07/webhooks.

Verifying Payloads

Every event webhook request is signed with HMAC-SHA256. The signature follows the draft-cavage-http-signatures-12 standard.

Signed headers included in every request:

• (request-target)
• date
• digest
• host
• content-length

To verify a request:

1. Extract the Signature header
2. Reconstruct the signing string from the listed headers
3. Compute HMAC-SHA256 using your signing secret
4. Compare against the signature in the header

Request Headers

Header	Value
everactive-event-type	machine-alarm-state-change-event or trap-state-change-event
content-type	application/json
date	RFC 7231 date (used in signature verification)
digest	SHA-256 digest of the request body (used in signature verification)

Example Payloads

Machine Alarm State Change

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventTimestamp": 1699841520,
  "equipmentName": "Pump #4",
  "facility": "Plant 1",
  "location": "Building A",
  "machineStartAlarmState": "Good",
  "machineEndAlarmState": "Alarm",
  "machineId": "a1b2c3d4-0000-0000-0000-ef1234567890",
  "machineDetailUrl": "https://api.data.everactive.com/v2020-07/machines/a1b2c3d4-0000-0000-0000-ef1234567890",
  "machineInsightsUrl": "https://ims.shoplogix.com/machines/a1b2c3d4-0000-0000-0000-ef1234567890",
  "machineType": "pump",
  "sensorMacAddress": "AA:BB:CC:DD:EE:FF",
  "description": "Detected Machine State Change on Pump #4 from Good to Alarm"
}

Possible machineStartAlarmState / machineEndAlarmState values:

Value	Meaning
Good	Below all configured vibration thresholds
Alarm	Above one or more configured thresholds
Acknowledged	Alarm has been acknowledged by a user in Insights

Steam Trap State Change

{
  "eventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "eventTimestamp": 1699798320,
  "facility": "Plant 1",
  "location": "Building C — Line 3",
  "sensorMacAddress": "AA:BB:CC:DD:EE:FF",
  "serviceTag": "ST-142",
  "trapStartState": "Good",
  "trapEndState": "Unexpected Cold Condition",
  "trapID": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "trapDetailUrl": "https://api.data.everactive.com/v2020-07/steam-traps/c3d4e5f6-a7b8-9012-cdef-123456789012",
  "trapInsightsUrl": "https://ims.shoplogix.com/steam-traps/c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Possible trapStartState / trapEndState values:

Value	Meaning
Good	Trap is operating normally
Blowthrough	Trap has failed open — passing steam continuously
Intermittent Blowthrough - Light	Low-frequency, low-volume intermittent blowthrough
Intermittent Blowthrough - Medium	Moderate intermittent blowthrough
Intermittent Blowthrough - Heavy	High-frequency, high-volume intermittent blowthrough
Leaking By	Partial failure — some steam passing when trap should be closed
Unexpected Cold Condition	Steam stopped unexpectedly during an operational period

note

eventTimestamp is a Unix timestamp (seconds since epoch). Both payloads may include an integrationInfo object when the asset is linked to a partner integration (e.g., Armstrong SAGE).

Delivery Guarantees

• Automatic retry — failed deliveries are retried with backoff
• Dead-letter queue — persistently failed deliveries are captured for review; contact your account team if you suspect missed events
• Delivery logs — receipts are retained for audit purposes

---

Data Streaming Webhooks (Data Services v1)

Data Services streaming webhooks push raw sensor readings and gateway status messages to your HTTP endpoint as they arrive — typically every ~60 seconds per sensor. This is the best choice for feeding sensor data into a custom pipeline, data historian, or OT platform that can accept HTTP but cannot use MQTT.

Supported Event Types

Event Type	What Gets Delivered
sensor_reading	Raw sensor readings from Eversensors (temperature, vibration, etc.)
gateway_status	Gateway connectivity and health status messages

Registering a Data Streaming Webhook

Manage streaming webhook subscriptions via the REST API at /ds/v1/webhooks (requires the Developer role).

Each subscription includes:

Field	Required	Description
callbackUrl	Yes	Your HTTPS endpoint that will receive the data
eventType	Yes	sensor_reading or gateway_status
customerId	Yes	The customer account whose data to stream
enabled	Yes	true to activate the subscription
headers	No	Custom key/value headers to include in each request (e.g., an API key your endpoint requires)
errorHandling	No	Retry configuration (see below)

Retry Configuration

The errorHandling object lets you tune delivery retry behavior:

Field	Description
retryDelay	Initial delay (ms) before the first retry
retryBackoff	Multiplier applied to delay on each subsequent retry
maxRetries	Maximum number of delivery attempts before giving up
requestTimeout	Timeout (ms) for each HTTP request to your endpoint

If all retries are exhausted, the message is routed to a dead-letter queue. Contact your account team if you suspect delivery failures.

Endpoint Requirements

For both webhook types, your endpoint must:

• Accept POST requests
• Return a 2xx status code within the request timeout to acknowledge receipt
• Be accessible from the public internet (or reachable via your network configuration)

If your endpoint is behind a firewall, contact your account team for the list of Shoplogix source IP ranges to allowlist.

---

Choosing Between Webhooks and Other Integrations

Use Case	Best Path
Alert your team when a machine goes into alarm	Event Webhook (/v2020-07/webhooks)
Trigger a CMMS work order on trap condition change	Event Webhook + Partner Integration
Stream all raw sensor data to a custom HTTP endpoint	Data Streaming Webhook (/ds/v1/webhooks)
Stream sensor data via MQTT	Data Broker
Query current or historical data on demand	REST API