Get started

Webhooks

Webhooks

Mountaya records every change in your organization as a webhook event: a member's role changed, an itinerary published, an invoice paid. It sends each event, signed, to the https endpoints you register.

Event
{
  "id": "019a8eed-e1ad-7753-b049-b0e20d79577a",
  "object": "webhook_event",
  "type": "organization.member.updated",
  "api_version": "0.8.0",
  "created_at": "2026-11-14T09:12:44Z",
  "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
  "task": "organization.member.update",
  "related_object": {
    "type": "organization.member",
    "id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1"
  },
  "data": {
    "object": {
      "object": "organization.member",
      "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1",
      "role": "contributor",
      "joined_at": "2026-03-11T14:02:09Z"
    },
    "previous_attributes": {
      "role": "viewer"
    }
  },
  "request": {
    "id": "2c5ed6d8b8f7c706e9a0d5c5144ed90b"
  },
  "actor": {
    "type": "user",
    "user_id": "1b9d4e72-0c35-4a8f-b6e1-5f2c7d904a18",
    "key_id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916"
  }
}

Receive events

  1. Create an endpoint and pick the event types it is sent.
  2. Verify the signature of each delivery, on the raw body.
  3. Answer 2xx within 10 seconds, then process the event.

What to rely on

  • At least once. One event can arrive twice. Deduplicate on its id.
  • In no promised order. Order one resource's events by the version its object carries, or read the resource.
  • Lean payloads. data.object holds identifiers and short fields, never geometry or credentials.
  • Retried for about 72 hours. After that, recover what you missed: events stay listed for 13 months.

The envelope

Every event arrives in the same envelope.

FieldHolds
idThe event's identifier, sortable by time. Deduplicate on it.
typeWhat happened, such as organization.member.updated.
taskThe task that recorded it.
related_objectThe type and id of the object it is about.
data.objectThat object, once changed.
data.previous_attributesThe fields the change moved, with their former values.
request.idThe X-Request-Id of the API call that caused it, or null.
actorWho made the change: a user, a key, or Mountaya.

Event types documents every field and every type.

Webhook events and live streams

The Map Studio API's …/events streams serve open editors. They push changes while a client holds the connection, and keep almost nothing. Webhook events serve your servers: Mountaya keeps them, signs them, and retries until your endpoint answers.

Live streamsWebhook events
Built forAn open editor or studioYour server
ConnectionYour client holds it openMountaya calls your endpoint
While you are offlineAbout an hour is replayedRetried for about 72 hours, listed for 13 months
CoversItineraries, zones and collectionsEvery change in the organization

Use both: a stream to refresh what a person is looking at, webhook events to keep your systems in step.

Next steps

Last updated