Bookings Webhooks

This guide explains how to receive real-time notifications for booking events on the Plum Guide platform.

Overview

Webhooks allow you to receive instant notifications when booking events occur, such as new booking requests, confirmations, or cancellations. This eliminates the need to poll the API for booking updates.


Quick Start

1. Configure Bookings Webhook Endpoint

POST /v2/webhooks/config
Authorization: Bearer {your_token}
Content-Type: application/json

{
  "isActive": true,
  "endpoints": {
    "bookings": "https://your-domain.com/webhooks/bookings"
  }
}

2. Receive Booking Events

When a booking event occurs, your endpoint receives:

{
  "EventId": "550e8400-e29b-41d4-a716-446655440000",
  "Timestamp": "2025-01-15T10:30:00.0000000Z",
  "BookingCode": "PG-ABC123",
  "ListingId": null,
  "EventType": null,
  "ConversationId": null,
  "MessageId": null
}

Every event also has HostId: the host the event is for. A software partner that acts for many hosts sends it in X-Plum-Host-Id to fetch the details. See Connecting many hosts.

3. Fetch Booking Details

Use the booking code to get full details:

GET /v2/bookings/{bookingCode}
Authorization: Bearer {your_token}

Booking Events

We send a booking webhook when any of these things happens to a booking:

  • A guest starts a booking.
  • A guest requests a booking.
  • The host approves a request.
  • A guest books with Instant Book.
  • The host declines a request.
  • A request is declined automatically, or it expires.
  • The booking is cancelled.

The webhook does not say which of these happened: EventType is always null for booking webhooks. Fetch the booking with GET /v2/bookings/{bookingCode} and act on its status.


Webhook Payload

{
  "EventId": "550e8400-e29b-41d4-a716-446655440000",
  "Timestamp": "2025-01-15T10:30:00.0000000Z",
  "BookingCode": "PG-ABC123",
  "ListingId": null,
  "EventType": null,
  "ConversationId": null,
  "MessageId": null
}

Field names are in PascalCase, unlike the rest of the API. Every field is always present, even when it is null.

FieldTypeDescription
EventIdUUIDUnique identifier for this event (use for idempotency)
TimestampISO 8601When we sent the event, in UTC
BookingCodestringThe booking's unique code
ListingIdnullAlways null for booking events
EventTypenullAlways null for booking events
ConversationIdnullAlways null for booking events
MessageIdnullAlways null for booking events

Verifying the signature

Every webhook carries the header X-Signature: sha256=<hex>. The value is the HMAC-SHA256 of the raw request body, keyed with your signingSecret, written in lowercase hex. You get signingSecret when you create the configuration, and again when you call POST /v2/webhooks/config/secret/rotate.

const crypto = require('crypto');

function isValid(rawBody, header, signingSecret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', signingSecret).update(rawBody).digest('hex');
  return header && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Compute the signature on the raw body bytes, before you parse the JSON.


Configuration API

Create

POST /v2/webhooks/config
Content-Type: application/json
Authorization: Bearer {token}

{
  "isActive": true,
  "endpoints": {
    "bookings": "https://your-domain.com/webhooks/bookings"
  }
}

Update Configuration

PUT /v2/webhooks/config
Content-Type: application/json
Authorization: Bearer {token}

{
  "isActive": true,
  "endpoints": {
    "bookings": "https://your-domain.com/webhooks/bookings",
    "listings": "https://your-domain.com/webhooks/listings",
    "messages": "https://your-domain.com/webhooks/messages"
  }
}

Get Configuration

GET /v2/webhooks/config
Authorization: Bearer {token}

Toggle On/Off

PATCH /v2/webhooks/config/toggle?isActive=false
Authorization: Bearer {token}

Delete Configuration

DELETE /v2/webhooks/config
Authorization: Bearer {token}

Requirements:

  • Endpoint URL must use HTTPS
  • Your endpoint must return 200 OK within 30 seconds

Handling Booking Events

Booking Requested

A guest has requested to book. You must approve or decline:

app.post('/webhooks/bookings', async (req, res) => {
  res.status(200).send('OK');

  const { BookingCode: bookingCode } = req.body;
  const booking = await plumApi.getBooking(bookingCode);

  if (booking.status === 'Request') {
    // Review booking and approve/decline
    await notifyHostOfNewRequest(booking);
  }
});

Booking Confirmed (Instant Book)

The booking was automatically confirmed:

if (booking.status === 'Confirmed') {
  // Update your calendar
  await blockDates(booking.listingId, booking.checkIn, booking.checkOut);

  // Send confirmation to your system
  await createReservation(booking);
}

Booking Cancelled

Update availability when a booking is cancelled:

if (booking.status === 'Cancelled') {
  // Release the dates
  await unblockDates(booking.listingId, booking.checkIn, booking.checkOut);

  // Update your records
  await cancelReservation(booking.bookingCode);
}

Complete Example Handler

const processedEvents = new Set();

app.post('/webhooks/bookings', async (req, res) => {
  const { EventId: eventId, BookingCode: bookingCode } = req.body;

  // Idempotency check
  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }

  // Acknowledge receipt immediately
  res.status(200).send('OK');
  processedEvents.add(eventId);

  try {
    // Fetch full booking details
    const booking = await plumApi.getBooking(bookingCode);

    switch (booking.status) {
      case 'Request':
        await handleNewRequest(booking);
        break;
      case 'Confirmed':
        await handleConfirmation(booking);
        break;
      case 'Cancelled':
        await handleCancellation(booking);
        break;
      case 'Declined':
        await handleDecline(booking);
        break;
    }
  } catch (error) {
    console.error('Failed to process booking webhook:', error);
  }
});

Best Practices

  1. Respond quickly - Return 200 OK immediately, process asynchronously
  2. Implement idempotency - Use eventId to avoid processing duplicates
  3. Fetch full details - The webhook payload only contains BookingCode
  4. Handle all statuses - Process each booking status appropriately
  5. Log events - Keep records for debugging and auditing

Booking Statuses

When you fetch booking details, the status field indicates the current state:

StatusDescription
InitiatedBooking started but not completed
RequestGuest requested booking, awaiting approval
ConfirmedBooking is confirmed
DeclinedHost declined the booking
CancelledBooking was cancelled

Troubleshooting

Not receiving webhooks?

  1. Verify configuration: GET /v2/webhooks/config
  2. Check isActive is true
  3. Ensure endpoints.bookings is set
  4. Confirm URL is HTTPS and publicly accessible

Missing booking details?

The webhook only contains BookingCode. Fetch full details:

GET /v2/bookings/{bookingCode}

Receiving duplicates?

This is expected: we retry when your endpoint does not answer with a 2xx status. Use EventId for deduplication:

const processedEvents = new Set();

if (processedEvents.has(eventId)) {
  return res.status(200).send('Already processed');
}
processedEvents.add(eventId);

Testing

Test bookings

On staging (https://api.stg.plumguide.io), create a test booking with POST /testdata/booking. It sends the same booking webhooks as a real booking.

Local Development

Use ngrok to expose your local server:

ngrok http 3000

Then configure the webhook:

POST /v2/webhooks/config
{
  "isActive": true,
  "endpoints": {
    "bookings": "https://abc123.ngrok.io/webhooks/bookings"
  }
}

Testing Checklist

  • Endpoint returns 200 OK within 30 seconds
  • Handles duplicate events (same EventId)
  • Checks the X-Signature header
  • Fetches full booking details via API
  • Processes all booking statuses correctly
  • Updates your system appropriately