Callbacks

Inbound webhooks from partner systems — e.g. the the registry access-control callback that records a gate tap. Authenticated by a shared secret header (not a user bearer token), so these routes must never be exposed to the public frontend.

1 endpoint(s)

POST the registry Access Control Callback {{url}}/callbacks/waas ▸

Public webhook — called by the TerraGo platform (not by the TerraGo frontend/app) to push real-time events into TerraGo: access-control taps at a gate/zone/location, wallet top-up confirmations, and SMS delivery receipts. Routes internally based on the event field.

Request Body (envelope)

event (string, required): One of:
ACCESSCONTROL / ZONECHECKIN / ZONECHECKOUT / DENIED — a tap-in/tap-out/denied event at a gate. data shape: { zoneid, person_id, status }.
WALLETTRANSACTIONCALLBACK — a parent's wallet top-up. Only type: "Top Up" payloads are processed; triggers a billing cycle for the parent.
SMS_CALLBACK — delivery status for a previously sent SMS. data shape: { phone, status: "delivered"|"failed", response }. Updates the matching Communication log entry.
data (object, required): Event-specific payload, see above.

Notes

No bearer token — authenticity relies on this being a server-to-server call from the the registry platform. ACCESS_CONTROL events are queued ({"queued": true}) and processed asynchronously, ultimately creating roll call / access log records.
Unrecognized event values are logged as warnings and otherwise ignored.

Response

200 acknowledgement (data); the tap event is recorded and processed. Returns 403 if the shared-secret header is missing or invalid.

Auth

Bearer token (inherited)

Request Body

// {
//     "event": "ZONE_CHECKOUT",
//     "data":{
//         "person_id":"55998eaf-93e6-4f2b-b0bc-bdeae82255f2",
//         "first_name":"Disi",
//         "last_name":"New",
//         "zone_id":"55169604-66a9-4eba-b35b-2448ea21ba86",
//         "zone":"KAP 123","zone_type":"Mobile",
//         "zone_tags":[
//                 {"id":"84561c7c-125c-4a96-97c8-3ba7ea5ca2e1","name":"Foundation","description":null,"entity":"universal","color_code":"#FF9500"},
//                 {"id":"5ac13004-3e77-4e9e-a9b8-be8080ce845e","name":"BACKSTAGE ACCESS","description":"test","entity":"universal","color_code":"#34C759"},
//                 {"id":"27ba6b10-c659-408f-beb1-dc650d5d5034","name":"VIP ACCESS","description":"VIP ACCESS","entity":"universal","color_code":"#9351E8"},
//                 {"id":"d4b18b8f-eaa6-44e1-8655-d75f146c0933","name":"PM School Tag","description":"PM School Tag","entity":"universal","color_code":"#EA0D8D"}
//             ],
//         "third_party_id":"09e85c35-5998-4362-beed-297c92a4e851",
//         "checkin_at":"2026-03-22 16:41:07",
//         "checkout_at":"2026-03-22 16:41:12",
//         "status":"Checked Out"
//     }
// }
{
    "event": "ZONE_CHECKIN",
    "data": {
        "person_id": "2f2ee36a-bfa5-4b07-b999-d41149125655",
        "first_name": "Pink",
        "last_name": "Terra",
        "zone_id": "55169604-66a9-4eba-b35b-2448ea21ba86",
        "zone": "KAP 123",
        "zone_type": "Mobile",
        "access_log_mode": "Manual",
        "zone_metadata": [
            {
                "key": "make",
                "value": "Isuzu Dmax"
            },
            {
                "key": "model",
                "value": "NQR"
            },
            {
                "key": "capacity",
                "value": 32
            },
            {
                "key": "consumption",
                "value": "3"
            },
            {
                "key": "fuel_type",
                "value": "Petrol"
            }
        ],
        "zone_tags": [
            {
                "id": "84561c7c-125c-4a96-97c8-3ba7ea5ca2e1",
                "name": "Foundation",
                "description": null,
                "entity": "universal",
                "color_code": "#FF9500"
            },
            {
                "id": "5ac13004-3e77-4e9e-a9b8-be8080ce845e",
                "name": "BACKSTAGE ACCESS",
                "description": "test",
                "entity": "universal",
                "color_code": "#34C759"
            },
            {
                "id": "27ba6b10-c659-408f-beb1-dc650d5d5034",
                "name": "VIP ACCESS",
                "description": "VIP ACCESS",
                "entity": "universal",
                "color_code": "#9351E8"
            },
            {
                "id": "d4b18b8f-eaa6-44e1-8655-d75f146c0933",
                "name": "PM School Tag",
                "description": "PM School Tag",
                "entity": "universal",
                "color_code": "#EA0D8D"
            }
        ],
        "third_party_id": "6c9c0aca-ec65-4dba-9717-f5a006d54503",
        "checkin_at": "2026-03-22 16:41:07",
        "checkout_at": null,
        "status": "Checked In"
    }
}