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

Schema 1.1 is additive. location and sensor remain. New keys: sensor_serial (stable mapping id), bed, room, event_type (seizure / bed_exit / bed_occupied / low_battery / sensor_fault, classified by CAPCODE only; occupancy is a legacy alias), capcode. Partners that still expect 1.0 can set payload_schema to 1.0 (new keys omitted).

{
    "type": "airlert.hub.message.ingested",
    "schema_version": "1.1",
    "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,
        "sensor_serial": "MAT-001",
        "bed": "Bed 1",
        "room": "Room 1",
        "event_type": "seizure",
        "capcode": "1234567"
    }
}

Authentication

• AIRlert generates Bearer tokens and POSTs them to your registered token_rotate_url as partner.token.rotated.
• On alert webhooks, check Authorization: Bearer ... against the current token (accept previous or new during the grace window).
• 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.

Token rotation endpoint

• Register token_rotate_url (example: /api/airlert-token-rotate).
• Event header: X-Airlert-Event: partner.token.rotated.
• Payload includes bearer_token, expires_at, grace_until, and previous_token_fingerprint.
• Return HTTP 200 or 202; AIRlert only activates the new token after a successful push.
• During grace_until, accept the previous token or the new one on the alert webhook.

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 (kinds ingest, token_rotate, optional connectivity / link_ping).
• Optional partner features may POST airlert.hub.connectivity.changed when an allowed HUB goes late/offline.

OpenAPI

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