Skip to main content

Receiving Events

Every event Mapped sends to your webhook is a CloudEvent (version 1.0) delivered in an HTTP POST. This page describes the request, how to check that it came from Mapped, and what to expect when your endpoint is slow or down.

The Event Envelope​

Every event has these attributes, whatever its type:

AttributeDescription
specversionAlways 1.0.
idUnique ID of the event. A retried delivery keeps the same id, so use it to de-duplicate.
typeWhat happened, for example mapped.livequery.resultChangeNotification.v1.created. See the event types.
sourceWhat it happened to, as a path that starts with your org, for example //com.mapped/orgs/ORG.../liveQueries/LVQ....
timeWhen the event was created, as an RFC 3339 timestamp in UTC.
datacontenttypeAlways application/json.
orgidThe ID of the org the event belongs to.
dataThe event's payload: a JSON object whose shape depends on type.

Events can also carry extensions: extra attributes with lowercase names. Some event types add their own, listed on the event's page, so you can filter or route without reading data. Mapped also adds tracing attributes such as traceid and correlationid, and you can add your own to every event a webhook sends with its eventExtensions (see Custom Extensions). Ignore extensions you don't recognize.

Content Modes​

A webhook's contentMode decides how the event is laid out in the request.

Binary (default)​

When contentMode is not set, or set to BINARY, the body is the event's data and every other attribute is an HTTP header prefixed with ce-:

POST /mapped/events HTTP/1.1
Content-Type: application/json
ce-specversion: 1.0
ce-id: LVQCH8x2c4Yq3cGmbFUqcm5H9Ad
ce-type: mapped.livequery.resultChangeNotification.v1.created
ce-source: //com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQAERav1iu5vkp6Qhkmf1234
ce-time: 2026-11-19T17:02:03.512Z
ce-orgid: ORG8Si1dkzGEYZgxrR4ZYAbCD
X-Mapped-OrgId: ORG8Si1dkzGEYZgxrR4ZYAbCD
X-Authorization-Digest: HMACSHA256
X-Mapped-Signature-0: DfV+OtRSnsuyQ0vUHVb1Pp6fGQdRmd8yNLXUyTfY0Ek=

{"lastResult":{"sites":[{"id":"SITETeZNmbxTZKbN6ArdANbyvX","name":"New Site"}]},"liveQueryId":"LVQAERav1iu5vkp6Qhkmf1234"}

Binary mode is the simplest to consume: the body is the payload, and you route on the ce-type header. HTTP header names are case-insensitive, so read them without depending on case.

Structured​

With contentMode: STRUCTURED, the body is the whole event as one JSON object, with Content-Type: application/cloudevents+json:

{
"specversion": "1.0",
"id": "LVQCH8x2c4Yq3cGmbFUqcm5H9Ad",
"type": "mapped.livequery.resultChangeNotification.v1.created",
"source": "//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQAERav1iu5vkp6Qhkmf1234",
"time": "2026-11-19T17:02:03.512Z",
"datacontenttype": "application/json",
"orgid": "ORG8Si1dkzGEYZgxrR4ZYAbCD",
"data": {
"lastResult": { "sites": [{ "id": "SITETeZNmbxTZKbN6ArdANbyvX", "name": "New Site" }] },
"liveQueryId": "LVQAERav1iu5vkp6Qhkmf1234"
}
}

Structured mode suits tools that expect the CloudEvents JSON format. If you verify signatures, use binary mode: its signature covers the request body exactly as sent.

The examples on the event pages show data, which is the body in binary mode and the data member in structured mode.

Authentication​

The webhook's httpTarget.auth decides what Mapped sends to authenticate itself to your endpoint:

OptionWhat your endpoint receives
noAuthNo credentials. Use a signing key so you can still verify requests.
basicAuthAuthorization: Basic <base64 of username:password>
apiKeyA header named keyName with the value apiKey.
oauth2ClientCredentialsFlowAuthorization: Bearer <token>, where Mapped gets the token from your tokenEndpoint with the client credentials grant, using clientId, clientSecret, and scope.

Credentials prove the request came from someone who knows them; a signature also proves the body was not changed. Use both where you can.

Verifying Signatures​

When a webhook has signing keys (httpTarget.hmac256.signingKeys), Mapped signs every request it sends:

HeaderValue
X-Authorization-DigestHMACSHA256
X-Mapped-Signature-0The signature made with the first signing key.
X-Mapped-Signature-1, …One more header for each further key, numbered from 0 in the order of signingKeys.

Each signature is the HMAC-SHA256 of the raw request body, keyed with the signing key, encoded as standard base64. To verify a request:

  1. Read the raw body before parsing it: parsing and re-serializing JSON changes the bytes.
  2. Compute the HMAC-SHA256 of the body with each signing key you accept, and base64-encode it.
  3. Accept the request if any computed value equals any X-Mapped-Signature-<n> header, compared in constant time. Otherwise answer 401.
import {createHmac, timingSafeEqual} from 'node:crypto';

// rawBody: the request body as a Buffer, before any JSON parsing.
export function isSignedByMapped(rawBody: Buffer, headers: Record<string, string | undefined>, keys: string[]): boolean {
const received = Object.entries(headers)
.filter(([name]) => /^x-mapped-signature-\d+$/i.test(name))
.map(([, value]) => Buffer.from(value ?? ''));
return keys.some((key) => {
const expected = Buffer.from(createHmac('sha256', key).update(rawBody).digest('base64'));
return received.some((r) => r.length === expected.length && timingSafeEqual(r, expected));
});
}

Rotating a Signing Key​

Because Mapped signs with every configured key, you can rotate without downtime:

  1. Add the new key to the webhook's signingKeys, keeping the old one.
  2. Accept either key in your endpoint.
  3. Remove the old key from the webhook, then from your endpoint.

Responding and Retries​

  • Success is any 2xx status within 10 seconds. The response body is ignored.
  • Anything else is a failure: another status, a timeout, or a connection error. Mapped sends the event again, up to the webhook's maxRetry times (10 when not set), waiting longer before each retry: the first retry comes within a minute or so, and the last of 10 retries comes a few hours after the first attempt.
  • After the last retry the event is dropped. Mapped does not disable a webhook that keeps failing, so fix the endpoint and reconcile what you missed.
  • maxRetry: 0 sends each event once, with no retries.

Duplicates and Ordering​

Delivery is at least once: the same event can arrive more than once, for example when your endpoint answered 2xx after the 10-second timeout. Every delivery of an event has the same id, so record the IDs you have processed for a while (a day is plenty) and skip repeats.

Events are not ordered. Mapped sends several requests to an endpoint at the same time, and a retried event can arrive after newer ones. Each event page says which fields tell you what is newest; the envelope's time is when the event was created.

Reconciling​

A webhook is a notification channel, not a ledger: an event can be lost, for example when your endpoint is down for longer than the retry window. Keep your copy correct by also reading the current state from the API, on a schedule or after an outage. Each event page names the query that returns the state the event describes.

Custom Extensions​

A webhook's eventExtensions adds fixed attributes to every event it sends, which helps when one endpoint serves several webhooks:

eventExtensions: { team: "facilities", priority: 2, production: true }
  • Names are 1 to 20 lowercase letters or digits. id, source, type, specversion, time, and orgid are reserved.
  • Values are strings, booleans, or whole numbers.
  • They arrive like any other attribute: as ce-team headers in binary mode, and as top-level members in structured mode. A webhook extension replaces an event attribute with the same name.