Send events to your own endpoint

Post IoTFlows events to a URL you control, and know what arrives before you write the handler.

A hosted endpoint is an HTTPS URL of your own that IoTFlows posts events to, as an HTTP POST with a JSON body. Endpoints belong to the organization rather than to one machine, so you add one once and choose which events it receives. They are configured self-serve in Organization Settings and are unrelated to REST API access, which IoTFlows grants by hand.

Prerequisites. Organization Owner or Organization Administrator, see Roles and permissions. An HTTPS URL that accepts a POST and returns a response, reachable from the public internet.

You do not need a hosted endpoint to reach Slack, Microsoft Teams or Discord. Each has a purpose-built integration that needs no code, see Send alerts to Slack, Teams, or Discord. Build an endpoint when the event has to reach something that is not a chat channel: a CMMS, an ERP, a dashboard of your own, or a queue.

What a hosted endpoint is

An endpoint is three things: a URL, a signing secret you choose, and a set of subscriptions, where a subscription is one event type switched on for that one endpoint. Nothing is delivered until at least one subscription is on.

Endpoints and machine event rules are separate systems. A rule on a machine's Event Notifications grid reaches people through email, push, SMS, the log, a work order and chat integrations, see Overview: alerts and integrations. A hosted endpoint subscribes to organization-level events and carries no per-machine switch, so there is nothing to turn on per asset.

You can add more than one endpoint, each with its own secret and its own subscriptions. Split them when two systems want different events, for example a maintenance system that wants faults and a reporting service that wants job completions.

Add an endpoint

1. Click the gear icon at the top right of the header. It opens Organization Settings at /settings/organization?select=settings.
2. Click Webhooks in the sub-navigation, at /settings/organization?select=webhooks. The page is headed Hosted endpoints and lists every endpoint in the organization by URL.
3. Click Add endpoint. The Listen to IoTFlows Events dialog opens.
4. Fill in the three fields below.
5. Click Verify. IoTFlows saves the endpoint and confirms with Endpoint created, then replaces the fields with Select events to listen to and a switch per event.
6. Switch on the events this endpoint should receive, then click Close. The endpoint was saved at step 5 and each switch saves as you flip it, so there is nothing left to submit.

The switch list inside the dialog carries event names only. The descriptions and the Test buttons are on the endpoint's row afterwards, see Choose which events to subscribe to.

Hosted endpoints. Configured in Organization Settings by an admin.

Endpoint fields

Verify is the save button. It creates the endpoint and confirms with Endpoint created. It does not show you what your handler will receive or whether your handler handled it. For that, send a test payload, see Send a test payload.

The Listen to IoTFlows Events dialog, with the endpoint URL, description and secret fields.

The signing secret

The signing secret is a string you choose when you create the endpoint. IoTFlows sends it back in the iotflows-secret header on every delivery, including test payloads, so your handler can reject a POST that did not come from IoTFlows.

Set one. The field accepts an empty value, and an endpoint with no secret has no way to tell an IoTFlows delivery from anything else that finds the URL. Use a long random string, for example the output of openssl rand -hex 32, and store it where your handler reads its own configuration.

Your handler compares the header with its stored copy and drops the request when they differ:

// Express handler for an IoTFlows hosted endpoint.
const express = require('express')
const app = express()

app.post('/hooks/iotflows', express.json(), (req, res) => {
  if (req.get('iotflows-secret') !== process.env.IOTFLOWS_WEBHOOK_SECRET) {
    return res.status(401).send('bad secret')
  }
  console.log('event received', req.body)
  res.status(200).send('ok')
})

app.listen(3000)

A delivery that passes the check prints the event and returns 200:

event received { data: { ... } }

To read the secret back later, expand the endpoint's row on the Hosted endpoints page. Secret is masked; click Reveal to show it and Hide to mask it again. The field is read-only there, so change a secret from the edit dialog, see Edit or remove an endpoint.

Because the secret can be read back, treat it as shared with everyone who can open Organization Settings. Give each endpoint its own secret rather than reusing a key your systems already rely on elsewhere.

The signing secret, masked by default.

Choose which events to subscribe to

Every endpoint on Hosted endpoints opens expanded. Under Events, each event IoTFlows can send is listed with its description and a Subscribe switch. Click the URL, or the chevron beside it, to collapse a row you are not working on.

Flip a switch and the change saves immediately. IoTFlows confirms with Subscribed to or Unsubscribed from, followed by the event's name. There is no Save button, and closing the page mid-list leaves the switches you already flipped in place.

This page does not reproduce the event list. The list is served by IoTFlows and can change without a release, and it cannot be exported, so any table printed here would be a copy that silently goes stale. Read it off the screen instead: the name and the one-line description in the Events column are the whole of what each event is.

Subscribe to the smallest set of events your system acts on. Every subscription is a delivery your endpoint has to accept and answer, and an endpoint that times out on events it ignores looks like an outage to whoever is watching it. If you cannot name what your handler does with an event, leave it off.

The subscribable events. This list is served by IoTFlows and read off the screen; it cannot be exported.

Send a test payload

Every event row carries a Test button, next to its switch. Click it to see the exact JSON IoTFlows sends for that event type, then click Test in the dialog to post that JSON to your endpoint.

Use it before you write the handler. The dialog shows the real shape of the body, so you can build against the field names rather than guessing them, and it states the header your handler must check: the secret arrives as iotflows-secret.

A test tells you two things and no more: that your URL answered, and what the body looks like. IoTFlows confirms a delivery with Message was sent successfully!, and reports a URL that did not answer as No response from server. Whether your handler did the right thing with the body is a question for your own logs.

The Test button works whether or not the event is subscribed, so you can check an endpoint end to end before you switch anything on.

A test payload for one event type, so you can build against the real shape.

Edit or remove an endpoint

Each row on Hosted endpoints ends in two controls.

• The pencil opens the same three fields, filled in. Change the URL, the description or the secret, then click Reverify. IoTFlows confirms with Endpoint updated. The new secret is used on the next delivery, so change your handler's copy in the same window or you will start rejecting valid deliveries.
• The trash opens a Delete Endpoint confirmation naming the URL. Click Delete and the endpoint goes, along with its subscriptions. IoTFlows confirms with Webhook has been removed.

Neither dialog touches subscriptions. Reverify saves the three fields and nothing else, and the edit dialog does not show the event switches at all.

Move a URL rather than replacing an endpoint. Editing keeps the subscriptions you have already chosen; deleting and re-adding means switching every event back on by hand.

Verify deliveries

IoTFlows shows you what it sent, not what your server did with it, so confirm deliveries at your end.

1. Send a test payload for one subscribed event, see Send a test payload.
2. Look for the request in your own server log, and check that the iotflows-secret header matched.
3. If No response from server appears, the URL did not answer. Check that it is reachable from the public internet, serves a valid TLS certificate, and returns a response rather than holding the connection open.
4. If your handler ran but did nothing, compare the body you received with the test payload for that event type. They are the same shape.

An endpoint that stops receiving after a deploy is usually a transport problem rather than a subscription one. The subscriptions survive a deploy; an expired certificate, a moved path and a firewall rule do not, and all three read the same way from the IoTFlows side, which is silence. Re-run the test before you touch any switches.

If an alert that should have reached your endpoint never fired in the first place, the problem is on the rule and not on the endpoint, see Troubleshoot alerts you did not receive.

See also

• Send alerts to Slack, Teams, or Discord
• Event types and channels
• Troubleshoot alerts you did not receive
• Overview: alerts and integrations
• Roles and permissions