Custom API for Call System Connector Partner developer guide

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

OpenAPI JSON Custom API overview Download HTML Sign in

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 your endpoint.
  4. Your endpoint verifies authentication and returns HTTP 200 or 202.
Request
MethodPOST
Content typeapplication/json; charset=utf-8
Event headerX-Airlert-Event: hub.message.ingested
Delivery idX-Airlert-Delivery-Id
User agentAIRLERT-OPEN-API/1.0

Your production endpoint is configured server-side. Example target format: http://live.airlert.co.uk/php/your-partner-endpoint

Payload

The payload shape is stable. Field names below match the OpenAPI document.

{
    "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 to verify
  • AIRlert generates Bearer tokens and pushes them to your token_rotate_url — do not rely on chat paste.
  • On alert deliveries, check Authorization: Bearer ... against the current token.
  • During the grace window after rotation, accept the previous token or the new one.
  • Check X-Airlert-Signature when a shared_secret is configured.
  • The signature format is sha256=<hex>.
  • The algorithm is HMAC-SHA256 over the exact raw JSON request body using shared_secret.
Token rotation URL

Register a HTTPS endpoint (example: /api/airlert-token-rotate) in partner config as token_rotate_url.

  • Method: POST with X-Airlert-Event: partner.token.rotated
  • JSON fields include event, partner, bearer_token, previous_token_fingerprint, activated_at, expires_at, grace_until
  • Return HTTP 200 or 202; AIRlert activates the new token only after a successful push
  • Optional: verify HMAC when shared_secret is set; bootstrap may omit Bearer until the first successful rotate
{
    "type": "airlert.partner.token.rotated",
    "schema_version": "1.0",
    "event": "partner.token.rotated",
    "event_id": "airlert-token-abcdef0123456789abcdef",
    "partner": "partner-cloud",
    "bearer_token": "hex-token-from-airlert",
    "previous_token_fingerprint": "sha256-hex-or-empty",
    "activated_at": "2026-07-15T08:00:00Z",
    "expires_at": "2026-08-14T08:00:00Z",
    "grace_until": "2026-07-16T08:00:00Z"
}
Response and logging
  • Return HTTP 200 or 202 when accepted.
  • Other statuses, cURL errors, timeouts, invalid URLs, or JSON encode failures are recorded as failed delivery attempts.
  • AIRlert logs each attempt in Outbound Traffic using channel open_api (ingest, token_rotate, optional connectivity / link_ping / link_watch kinds).
  • Optional: when enabled for your partner, AIRlert may POST airlert.hub.connectivity.changed if an allowed HUB goes late/offline (heartbeat rules), and may send light airlert.partner.link.ping probes.

Open Outbound Open API

OpenAPI document

Use the live OpenAPI JSON for schema validation and generated client/server code.

http://live.airlert.co.uk/php/airlert_open_api_spec.php