Webhooks and events

Add an endpoint in Mira Business under Settings, Webhooks: one for live events and, separately, one for test events. It must be HTTPS on port 443 or 8443 and reachable from the public internet. You see its signing secret once, when you add it or replace it.

By default an endpoint receives every event. In settings you can choose only some, by name or by whole group, for example delivery.*; a group also covers events added to it later. The test event is always sent.

A POST for each event, with the event in the body. Events carry ids and statuses only, never personal details: read the journey or vehicle through the API for more.

POST /your/webhook/path
Mira-Event-Id: 0192f1d0-2a4b-7c3d-8e9f-0a1b2c3d4e5f
Mira-Event-Type: delivery.completed
Mira-Timestamp: 1759140000
Mira-Signature: t=1759140000,v1=<64 hex characters>

{
  "id": "0192f1d0-2a4b-7c3d-8e9f-0a1b2c3d4e5f",
  "type": "delivery.completed",
  "apiVersion": "1.0.0",
  "livemode": true,
  "createdAt": "2026-10-02T14:03:11Z",
  "data": {
    "journeyId": "0192f1c2-6f3b-7d2a-9d6e-1a2b3c4d5e6f",
    "journeyType": "IDENTITY_DELIVERY",
    "journeyStatus": "COMPLETED",
    "externalReference": "DMS-88213",
    "customerReference": "5f1c7a9e-6f3b-4d2a-9d6e-1a2b3c4d5e6f",
    "deliveryStatus": "COMPLETED"
  }
}

v1 is the HMAC-SHA256 of t + "." + raw body, keyed with your endpoint's secret. Compute it over the exact bytes you received, before parsing the JSON, compare in constant time, and reject a t more than 5 minutes old so an old request cannot be replayed.

const crypto = require('crypto')

// rawBody must be the exact bytes received, before any JSON parsing.
function verifyMiraSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const given = Buffer.from(parts.v1 || '', 'hex')
  return given.length === 32 && crypto.timingSafeEqual(given, Buffer.from(expected, 'hex'))
}

• Any 2xx within 10 seconds counts as delivered. Redirects are not followed.
• Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours, then given up on.
• Events can arrive out of order: use createdAt, or read the record, for the latest state.
• If nothing reaches an endpoint for three days, Mira turns it off and emails your company admin. Fix it, save the URL again to turn it back on, and resend what you missed from the delivery log.

Every event has id, type, apiVersion, livemode, createdAt and data. Journey events carry the journey's ids and statuses; stock events carry your stock code. Events marked simulatable can be forced with a sandbox key.