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

• 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.