New

Add your parking space on parksby! List now

New Parksby is granting Early Access! Download the app!
Developers

Webhook Integration

Parksby sends booking and payment events to your system via signed webhooks. Add your endpoint during parking setup, store the secret key securely, and use this guide to verify and process events safely.

HMAC-SHA256 signed Reliable retries Idempotent processing
Contact the team View payload format

Quickstart

Four steps to a working receiver

  1. 1 Add your endpoint during parking setup
  2. 2 Store the secret key provided during setup
  3. 3 Verify the HMAC signature on every request
  4. 4 Deduplicate using event_id

Always compute HMAC over the raw request body. Parsed JSON will fail verification.

1. Overview

Parksby delivers booking and payment events to your webhook endpoint so your system stays in sync. You’ll add your endpoint when setting up a parking space, and you’ll receive a secret key for verification.

2. Supported Event Types

Event names are lowercase and case-sensitive.

payment.confirmed
booking.activated
booking.completed
booking.checked_in
booking.checked_out

3. Add Your Endpoint

You can add your webhook endpoint while setting up a parking space on Parksby. We’ll display a secret key at setup time — store it securely because it is used to verify webhook signatures.

What you provide

  • Your HTTPS endpoint URL
  • Events you want to receive

What you receive

  • A secret key for signature verification
  • A sample payload for testing your parser

4. Payload Snippet

You’ll see a sample payload during setup. Your webhook receives this JSON structure, with event-specific details inside the data object.

Webhook payload 
{
  "event_id": "uuid",
  "event_type": "payment.confirmed",
  "occurred_at": "2026-01-28T12:34:56Z",
  "data": {
    "booking_id": "uuid",
    "parking_id": "uuid",
    "tenant_id": "uuid",
    "vehicle_plate": "KXX 123X",
    "space_no": 5,
    "status": "completed",
    "payment_status": "paid",
    "payment_reference": "PSP_REF",
    "total_price": "1000.00",
    "final_price": "1000.00",
    "currency": "KES",
    "entry_time": "2026-01-28T10:00:00Z",
    "exit_time": "2026-01-28T11:00:00Z",
    "entry_source": "user",
    "exit_source": "hardware"
  }
}

5. Security: Signature Verification

Every request is signed with HMAC-SHA256 using the secret key provided during setup, and includes a timestamp for replay protection.

Headers

  • X-Parksby-Timestamp
  • X-Parksby-Signature
  • X-Parksby-Event-ID

Verification Steps

  1. Reject if timestamp > 5 min old
  2. Compute HMAC over raw body
  3. Deduplicate by event_id
Node.js example 
import crypto from "crypto";

const signature = req.headers["x-parksby-signature"];
const timestamp = Number(req.headers["x-parksby-timestamp"]);
const rawBody = req.rawBody; // Buffer or raw string

const tooOld = Math.abs(Date.now() / 1000 - timestamp) > 300;
if (tooOld) throw new Error("Stale webhook");

const expected = crypto
  .createHmac("sha256", process.env.PARKSBY_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  throw new Error("Invalid signature");
}

6. Retries & Idempotency

5
Max attempts
2n
Backoff (min)
4xx
Permanent fail
5xx
Retried
  • 4xx responses are permanent failures (except 429)
  • 5xx and network errors are retried with exponential backoff
  • Your handler must be idempotent using event_id

7. Troubleshooting Checklist

  1. Confirm your endpoint URL is correct and reachable
  2. Verify the secret key used for HMAC matches the one shown during setup
  3. Check that your endpoint responds with a 2xx status code
  4. Ensure your handler is idempotent using event_id
  5. Verify you subscribed to the exact event name

8. Quick Test

  1. Create an endpoint subscribed to payment.confirmed
  2. Complete a booking payment in your test environment
  3. Confirm your endpoint receives the POST request
  4. Validate the signature using your secret key