AIRLERT-OPEN-API Partner Developer Guide

AIRlert POSTs selected HUB messages to a partner HTTPS endpoint as signed JSON. The partner system verifies the request, stores or routes the event, and returns an accepted HTTP status.

Flow

1. A HUB message is ingested by AIRlert.
2. The portal stores it in user_data.
3. If the HUB is in allowed_hub_ids, AIRlert POSTs the event to the partner endpoint.
4. The partner endpoint verifies authentication and returns HTTP 200 or 202.

Request

• Method: POST
• Content type: application/json; charset=utf-8
• Event header: X-Airlert-Event: hub.message.ingested
• Delivery id: X-Airlert-Delivery-Id
• User agent: AIRLERT-OPEN-API/1.0

Payload

{
    "type": "airlert.hub.message.ingested",
    "schema_version": "1.0",
    "event_id": "airlert-9a8b7c6d5e4f3210abcd1234-a1b2c3d4",
    "occurred_at_unix": 1781766000,
    "occurred_at": "2026-06-18T06:20:00Z",
    "source": "airlert_portal",
    "ingest_endpoint": "tttupload.php",
    "hub": {
        "canonical_hub_id": 42,
        "user_data_hub_id": 42,
        "hub_name": "Bedroom hub",
        "user_id": 3
    },
    "message": {
        "location": "Room 1",
        "sensor": "Bed pad",
        "raw": "Not Return to Bed",
        "presented": "Not Return to Bed",
        "user_data_id": 123456
    }
}

Authentication

• Check Authorization: Bearer ... against the agreed token.
• Check X-Airlert-Signature when shared_secret is configured.
• The signature format is sha256=<hex>.
• The algorithm is HMAC-SHA256 over the raw JSON request body using shared_secret.

Response and logging

• Return HTTP 200 or 202 when accepted.
• Other statuses, cURL errors, timeouts, invalid URLs, or JSON encode failures are logged as failed attempts.
• Delivery attempts appear in Outbound Traffic under channel open_api.

OpenAPI

Use airlert_open_api_spec.php on the portal for the live OpenAPI JSON document.