Webhooks

Setup

Configure webhooks in your dashboard. Provide an HTTPS endpoint URL and select the events you want to receive. Each event is sent to every active endpoint subscribed to it, for all of your lots. Events are queued when they happen and sent separately from the request that caused them, so a slow endpoint never delays a driver's checkout. The dashboard shows every delivery attempt.

Events

Subscribe to one or more of these seven event types:

Session, reservation, pricing and payment lifecycle

Six more events follow a session from hold to refund. Choose them the same way, in the dashboard or with POST /api/v1/webhooks. They are queued, signed, retried and logged exactly like the events above.

Alerts and daily stats

Two more events report on your lots as a whole, on Pro and Enterprise. Choose them the same way. They are queued, signed, retried and logged exactly like the events above.

Subscribe via API

Programmatically register a webhook endpoint and choose the events you want to receive:

curl -X POST https://parkgraph.com/api/v1/webhooks \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/parkgraph",
    "events": ["session.created", "session.ended", "payment.completed"]
  }'

Payload Format

Every event has the same envelope: id (the same on every retry), type, created_at (when the event happened) and data. Amounts are in dollars.

{
  "id": "evt_3f2a9c1e0b7d4e58a6c1f0d2b9e47a13",
  "type": "session.created",
  "created_at": "2026-04-30T10:00:00Z",
  "data": {
    "session_id": "uuid",
    "session_code": "PG-VV7891",
    "lot_id": "uuid",
    "lot_name": "Vail Village Parking",
    "vehicle_plate": "CO-7891",
    "status": "active",
    "source": "agent",
    "agent_name": "claude",
    "effective_rate": 8.00,
    "rate_unit": "hour",
    "started_at": "2026-04-30T10:00:00Z",
    "expected_end": "2026-04-30T12:00:00Z",
    "duration_hours": 2
  }
}

session.ended carries the same session fields plus ended_at, subtotal, platform_fee, owner_payout, currency and payment_status. session.extended adds extended_count, previous_expected_end and subtotal.

{
  "id": "evt_8b1d0e6f2c3a4b7d9e5f1a2c3d4e5f60",
  "type": "payment.completed",
  "created_at": "2026-04-30T11:45:00Z",
  "data": {
    "session_id": "uuid",
    "session_code": "PG-VV7891",
    "lot_id": "uuid",
    "kind": "session",
    "extension_number": null,
    "subtotal": 14.00,
    "platform_fee": 1.40,
    "owner_payout": 12.60,
    "currency": "usd",
    "payment_intent_id": "pi_...",
    "captured_at": "2026-04-30T11:45:00Z"
  }
}

kind is session or extension. payment.failed sends session_id, lot_id, payment_intent_id, failure_code (Stripe's decline code), amount, currency and occurred_at.

{
  "id": "evt_c4d5e6f7a8b9405162738495a6b7c8d9",
  "type": "occupancy.changed",
  "created_at": "2026-04-30T17:20:00Z",
  "data": {
    "lot_id": "uuid",
    "lot_name": "Vail Village Parking",
    "direction": "above",
    "threshold_pct": 90,
    "occupancy_pct": 92,
    "occupied_spaces": 46,
    "total_spaces": 50,
    "available_spaces": 4
  }
}

direction is above or below. A crossing caused by a lot settings change, such as adding spaces or raising the alert level, carries the new total_spaces and threshold_pct. Changes that leave the lot on the same side send nothing.

{
  "id": "evt_0a1b2c3d4e5f46a7b8c9d0e1f2a3b4c5",
  "type": "lot.updated",
  "created_at": "2026-04-30T09:12:00Z",
  "data": {
    "lot_id": "uuid",
    "lot_name": "Vail Village Parking",
    "changes": ["total_spaces"],
    "lot": {
      "lot_id": "uuid",
      "name": "Vail Village Parking",
      "slug": "vail-village-parking",
      "status": "active",
      "listed": true,
      "agent_bookable": true,
      "address": "241 E Meadow Dr",
      "city": "Vail",
      "state": "CO",
      "zip": "81657",
      "timezone": "America/Denver",
      "total_spaces": 50,
      "ev_spaces": 4,
      "handicap_spaces": 2,
      "retired_at": null
    }
  }
}

A pricing change sends lot.updated with "changes": ["pricing"]; read the new rates from the API.

session.started carries the same session fields as session.created. pricing.rule_triggered adds base_rate, multiplier, effective_rate, rate_unit and currency. reservation.created sends hold_id, lot_id, lot_name, space_count, held_by (api_key or anonymous), quoted_price, created_at and expires_at; reservation.cancelled adds reason and cancelled_at. payment.captured has the same fields as payment.completed.

pricing.rule_triggered also carries rule, the rule that set the price: event, surge_today, busy_lot, peak, weekend or stacked (more than one multiplied together). A flat event price sends it too, with multiplier 1 and rate_unit flat. rule is null only on sessions created before the rule was recorded.

{
  "id": "evt_5e6f7a8b9c0d41e2f3a4b5c6d7e8f9a0",
  "type": "payment.refunded",
  "created_at": "2026-04-30T15:02:00Z",
  "data": {
    "session_id": "uuid",
    "session_code": "PG-VV7891",
    "lot_id": "uuid",
    "kind": "session",
    "extension_number": null,
    "subtotal": 14.00,
    "platform_fee": 1.40,
    "owner_payout": 12.60,
    "currency": "usd",
    "payment_intent_id": "pi_...",
    "captured_at": "2026-04-30T11:45:00Z",
    "amount_refunded": 5.00,
    "total_refunded": 5.00,
    "fully_refunded": false,
    "refund_id": "re_...",
    "refunded_at": "2026-04-30T15:02:00Z"
  }
}

amount_refunded is what this refund gave back; total_refunded is everything refunded on that payment so far.

Signature Verification

Every webhook includes an X-Park-Graph-Signature header whose value is sha256=<hex>. Strip the sha256= prefix, recompute the HMAC over the raw request body, and compare to verify the webhook is authentic. Each delivery also carries X-Park-Graph-Event (the event type) and X-Park-Graph-Delivery (the event id, stable across retries).

import crypto from "crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  // Header arrives as "sha256=<hex>" — strip the scheme prefix.
  const received = signatureHeader?.startsWith("sha256=")
    ? signatureHeader.slice("sha256=".length)
    : signatureHeader;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(received),
    Buffer.from(expected)
  );
}

// In your endpoint handler (verify against the RAW request body):
const isValid = verifyWebhook(
  rawBody,
  req.headers["x-park-graph-signature"],
  "whsec_..."
);

Retry Policy

Resend a Missed Event

If your server was down or your handler had a bug, you can send an event again instead of rebuilding the data from the API. An event can be resent when it failed every attempt or was cancelled because the endpoint was paused, for 7 days after it happened. In the dashboard, open an endpoint's delivery log and press Resend on the event.

A resend is one attempt, made right away, with the same body, signature scheme and X-Park-Graph-Delivery id as the original, so a receiver that skips ids it has already handled stays correct. It appears in the delivery log as the event's next attempt. A successful resend marks the event delivered and resets the endpoint's failure count; a failed one is not retried and does not count toward pausing the endpoint. Resume a paused endpoint before resending its events.

From the API, use a key with the webhooks:manage scope. List an endpoint's attempts, newest first. Each one carries its event's current event_status (pending, delivered, failed or cancelled) and resendable. Events cancelled before their first attempt have no attempt to show, so they are listed in unsent_events, also newest first, with their ids:

curl "https://parkgraph.com/api/v1/webhooks/deliveries?webhook_id=<webhook id>&limit=50" \
  -H "Authorization: Bearer pk_live_..."

{
  "deliveries": [
    {
      "id": "uuid",
      "event_id": "evt_3f2a9c1e0b7d4e58a6c1f0d2b9e47a13",
      "event_type": "session.created",
      "attempt": 7,
      "success": false,
      "status_code": 503,
      "duration_ms": 1204,
      "error": "Endpoint answered HTTP 503",
      "next_retry_at": null,
      "created_at": "2026-04-30T07:01:00Z",
      "event_status": "failed",
      "resendable": true
    }
  ],
  "deliveries_next_cursor": "WyJkIiwiMjAyNi0wNC0zMFQwNzowMTowMFoiLCIuLi4iXQ",
  "unsent_events": [
    {
      "event_id": "evt_9b1c47e2d05a4f3c8e6a2d7f10b3c5e8",
      "event_type": "lot.updated",
      "event_status": "cancelled",
      "reason": "Endpoint is paused",
      "created_at": "2026-04-30T07:40:00Z",
      "resendable": true
    }
  ],
  "unsent_events_next_cursor": null
}

Each list returns up to limit items (1–100, default 20) and its own next cursor, null once there is nothing older. To go back further, pass that value as cursor; the response then holds the next page of that list only. Keep paging until the cursor is null to reach every event from the last 7 days. Resending events while you page doesn't make you miss any.

curl "https://parkgraph.com/api/v1/webhooks/deliveries?webhook_id=<webhook id>&limit=50&cursor=<deliveries_next_cursor>" \
  -H "Authorization: Bearer pk_live_..."

Then resend an event by its id. The call waits for your endpoint (up to 30 seconds) and returns the new attempt; success says whether your endpoint accepted it.

curl -X POST https://parkgraph.com/api/v1/webhooks/deliveries/evt_3f2a9c1e0b7d4e58a6c1f0d2b9e47a13/resend \
  -H "Authorization: Bearer pk_live_..."

{
  "delivery": {
    "id": "uuid",
    "event_id": "evt_3f2a9c1e0b7d4e58a6c1f0d2b9e47a13",
    "event_type": "session.created",
    "attempt": 8,
    "success": true,
    "status_code": 200,
    "duration_ms": 312,
    "error": null,
    "created_at": "2026-04-30T09:15:00Z"
  }
}