GeoRelay Cloud
Home Playground OpenAPI JSON

Integration Docs

Webhook API + Real-Time Playground

Send full snapshot and merge updates, validate payloads, and watch map updates live.

OpenAPI JSON Back to App

Protocol + Authentication

HTTP Protocol

  • `POST` JSON payloads with `Content-Type: application/json`.
  • Use HTTPS in production.
  • Expect `202 Accepted` when the payload is accepted.

Webhook URL

  • Map-specific endpoint: `/webhook/maps/{webhookKey}`.
  • Use the URL key (`webhookKey`) plus required header token for authentication.
  • Each map URL has isolated state for your use case.

Required Header Token

  • Send `x-webhook-token: <token>` on every map webhook request.
  • Supported alternative: `Authorization: Bearer <token>`.
  • Invalid or missing token returns `401`.

Update Modes

replace vs merge payload examples

Full Snapshot (`replace`)

Replaces the entire state with the payload. Use this when you are sending a complete current snapshot. 

{
  "updateMode": "replace",
  "eventGroups": [
    {
      "name": "Open",
      "color": "#1F77B4",
      "events": [
        {
          "id": "INC-1001",
          "geoCode": { "latitude": 33.749, "longitude": -84.388 },
          "eventCode": "INC-1001",
          "status": "Open"
        }
      ]
    }
  ],
  "summary": {
    "open_events": 1,
    "in_process": 0
  }
}
curl -X POST "/webhook/maps/{webhookKey}" \
  -H "Content-Type: application/json" \
  -H "x-webhook-token: YOUR_TOKEN" \
  -d '{...replace payload...}'

Incremental (`merge`)

Upserts changed/new event IDs and optionally removes IDs listed in `removedIds` without replacing untouched events. 

{
  "updateMode": "merge",
  "removedIds": ["INC-0998"],
  "eventGroups": [
    {
      "name": "InProcess",
      "color": "#0000FF",
      "events": [
        {
          "id": "INC-1001",
          "geoCode": { "latitude": 33.749, "longitude": -84.388 },
          "status": "InProcess",
          "driver": "Jane Doe"
        }
      ]
    }
  ],
  "summary": {
    "open_events": 0,
    "in_process": 1
  }
}
curl -X POST "/webhook/maps/{webhookKey}" \
  -H "Content-Type: application/json" \
  -H "x-webhook-token: YOUR_TOKEN" \
  -d '{...merge payload...}'

Quick Embed

iframe and widget snippets

Use these snippets for fast onboarding. The embed URL auto-syncs when your map is resolved.

Embed views are read-only and do not require the webhook token. Keep webhook tokens server-side and send them only on POST /webhook/maps/{webhookKey} requests.

IFrame Embed

Drop this into any HTML page to show a map-only view.

JavaScript Widget

Programmatic embed with lightweight runtime options.

Resolve a map first (temporary URL or first accepted payload) to generate production-ready embed URLs.

API Playground

send payloads and preview live behavior
Use this domain for webhook testing.
Sample Data Generator
8%
Auto refresh stopped.
Payload Editors

Request + Response

Ready.

No response yet.
Launch Map Experience
Generate a webhook URL to enable launch links.

Live Feed Preview

Connecting stream...

Map Visual Controls
1.2s
Groups0
Events0
Last Update-
No summary data.

    OpenAPI Reference

    Loading /openapi.public.json ...