Webhooks

Beta. Webhook support is under development. This page documents the planned architecture.

Receive real-time notifications when discrepancies are created, updated, or resolved.

Planned Events

Event	Description
`discrepancy.created`	A new discrepancy has been detected
`discrepancy.updated`	A discrepancy's status, confidence, or evidence has changed
`discrepancy.resolved`	A discrepancy has been resolved

Payload Format

JSON

{
  "id": "evt_...",
  "type": "discrepancy.created",
  "created_at": "2026-07-13T07:00:00Z",
  "data": {
    "discrepancy": {
      "id": "disc_...",
      "type": "possible_unreported_closure",
      "status": "active",
      "location": {
        "road_name": "Halleck Street",
        "latitude": 37.801,
        "longitude": -122.456
      },
      "confidence": 0.91,
      "summary": "Possible road-state information gap detected"
    }
  }
}

Signature Verification

Webhook payloads will be signed using HMAC-SHA-256. The signature will be included in the Road-Reality-Signature header.

Verification (planned)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Status