GeoRelay Cloud
Home Pricing 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 Pricing 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`.
Operational Rules

Event-driven rules like status changes and geofence enter/exit fire directly from incoming updates. Time-based rules such as dwell time, missing updates, density spikes, and SLA breach should be treated as Beta until you run the internal rule sweep worker or cron trigger in production.

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