Integrations

MQTT, webhooks and UDP

Connect face recognition to Node-RED, ioBroker, openHAB, n8n or your own scripts over MQTT, HTTP webhooks or UDP.

On this page

For everything that is not Home Assistant, Loxone or KNX, Node-RED, ioBroker, openHAB, n8n, a script of your own, FaceStream.AI has three general connection types. Each sends a message you write yourself, with placeholders for the name, the camera, the time and the links to the pictures.

Type	Choose it when	Edition
MQTT	The receiving system has a broker, or can use one	Pro and up
HTTP	The receiving system accepts a web request, a webhook	Pro and up
UDP	The receiving system listens on a port, or you have the Free edition	all

As with every connection, a rule decides when a message goes out, see Connections and rules.

MQTT

Field	What it does
Broker, Port	The broker's address and port, `1883` unless yours differs
User, Password	The broker account for FaceStream.AI
Topic	Where the message is published. Placeholders work: `facestream/[[camera_id]]/[[event]]` gives one topic per camera and event
QoS	0 at most once, 1 at least once, 2 exactly once
Retain	The broker keeps the last message for anyone who subscribes later
Message	The payload
Home Assistant discovery	Separate from all of the above, see Home Assistant

The default message is JSON:

{"name": "Amelia Hart", "camera": "Front Door", "at": "2026-09-22T14:32:05+02:00", "known": "true"}

To watch what arrives, subscribe with any MQTT client, for example:

mosquitto_sub -h 192.168.1.30 -u facestream -P '…' -t 'facestream/#' -v

Use [[camera_id]] rather than [[source]] in a topic: the ID never changes and has no spaces. And think twice before ticking Retain, the broker then keeps the name of the last person seen for anybody who subscribes.

Node-RED: an mqtt in node on the topic, a json node, and a switch node on msg.payload.name. ioBroker and openHAB: their MQTT adapters and bindings turn the topic into a state or an item; with a JSON payload, map the field you need.

HTTP webhooks

Field	What it does
URL	The address to call. Placeholders work here too
Method	POST, GET or PUT. GET sends no message
Extra headers	One per line, as `Name: value`
Bearer token	Sent as `Authorization: Bearer …`
Message	The body. If it is valid JSON, it goes out as `application/json`, otherwise as plain text

The default body:

{"name": "Amelia Hart", "camera": "Front Door", "at": "2026-09-22T14:32:05+02:00", "image_url": "http://192.168.1.20:8000/event-image/…"}

An answer with a status of 400 or higher counts as failed. Recent deliveries shows the status of every call, and for a successful one the start of the answer. FaceStream.AI waits up to three seconds for the connection and eight for the answer, then gives up.

Node-RED

An http in node, method POST, URL /facestream, and an http response node at the end of the flow. Without it, Node-RED never answers, and FaceStream.AI reports the call as failed after eight seconds. The URL in FaceStream.AI is then http://<node-red>:1880/facestream.

n8n

A Webhook node with the HTTP method POST. Use its production URL in FaceStream.AI; the test URL only listens while the workflow editor waits for a call.

Home Assistant without MQTT

If you would rather not run a broker, an automation with a webhook trigger also works without the devices that discovery creates:

triggers:
  - trigger: webhook
    webhook_id: facestream-front-door
    allowed_methods: [POST]
    local_only: true

In FaceStream.AI: URL http://<home assistant>:8123/api/webhook/facestream-front-door, method POST, and in the automation trigger.json.name is the name. Choose a webhook ID nobody can guess: anyone who knows it can start the automation.

UDP

Field	What it does
Host, Port	Where the datagram goes
Message	The content. By default `{"name": "[[name]]", "camera": "[[source]]", "at": "[[iso]]"}`

UDP is not acknowledged. Recent deliveries can only say how many bytes were sent, not whether anything received them.

To see what arrives, listen on the port on any computer:

nc -u -l 5000

The Loxone Miniserver has a Virtual UDP Input for this, see Loxone with the Free edition, and Node-RED a udp in node.

Writing the message

The message is a template: FaceStream.AI replaces the placeholders and sends the rest as it is. Three things save time:

Quote placeholders in JSON that can contain spaces or words: "name": "[[name]]", "liveness": "[[liveness]]", the liveness check writes not checked when it did not run. Numbers and truth values may go without quotes: "known": [[known]] becomes "known": true, "sightings": [[sightings]] a number.
Send the event, "event": "[[event]]", if one connection serves several rules, the receiver can then tell an arrival from a departure.
Send links, not pictures. [[image_url]] and [[frame_url]] open without signing in, from any machine that can reach FaceStream.AI's address.