Consume Mappls events exactly once in effect

Define the user and system contract

A consumer must apply each Mappls event once in business effect even when delivery is duplicated, delayed, reordered, or retried. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Expose one safe receiver

Deploy a public DNS hostname on HTTPS port 443 with a bounded path and no URL credential, query, redirect, fragment, IP literal, private name, or alternate port. Keep every A and AAAA answer public; Mappls validates and pins all answers on every attempt.

type AssetEvent = {
  id: string;
  assetId: string;
  occurredAt: string;
  type: "position" | "ignition" | "geofence.entered" | "geofence.exited";
  position?: { latitude: number; longitude: number; speedKph?: number };
};

export async function handleAssetEvent(event: AssetEvent) {
  // Idempotency matters: delivery may be retried.
  if (await events.exists(event.id)) return;
  await events.transaction(async () => {
    await events.record(event);
    await assets.apply(event.assetId, event);
  });
}

Prove destination ownership

Create the endpoint in pending state, validate the signed webhook.endpoint_verification.v1 envelope, compute the versioned challenge proof with the endpoint secret, and return it in x-mappls-verification-response before requesting business or synthetic events.

Verify before parsing

Read the exact raw body, validate timestamp freshness, event identity, and HMAC in constant time, then reject unknown versions or oversized payloads.

Commit inbox and effect together

Insert the event ID/content hash, validate aggregate version, apply the domain transition, and append downstream work in one transaction.

Recover deliberately

Return 2xx only after commit, retry transient dependencies out of band, quarantine conflicts, and replay from immutable evidence with an attributable operator reason. Issue a fresh ownership challenge after expiry; never replay one.

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when every dns answer stays public and the receiver does not redirect; destination ownership is proven before business fan-out; the same event id and body is a replay; changed content under one id is rejected; out-of-order transitions do not regress state. Capture provider request identity without logging credentials or unnecessary precise location.

Failure modes you must exercise

Definition of done

REST production checks

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.