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.
| Field | Type | Description |
|---|---|---|
EventId | UUID | Unique identifier for this event (use for idempotency) |
Timestamp | ISO 8601 | When we sent the event, in UTC |
BookingCode | string | The booking's unique code |
ListingId | null | Always null for booking events |
EventType | null | Always null for booking events |
ConversationId | null | Always null for booking events |
MessageId | null | Always 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 OKwithin 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
- Respond quickly - Return
200 OKimmediately, process asynchronously - Implement idempotency - Use
eventIdto avoid processing duplicates - Fetch full details - The webhook payload only contains
BookingCode - Handle all statuses - Process each booking status appropriately
- Log events - Keep records for debugging and auditing
Booking Statuses
When you fetch booking details, the status field indicates the current state:
| Status | Description |
|---|---|
Initiated | Booking started but not completed |
Request | Guest requested booking, awaiting approval |
Confirmed | Booking is confirmed |
Declined | Host declined the booking |
Cancelled | Booking was cancelled |
Troubleshooting
Not receiving webhooks?
- Verify configuration:
GET /v2/webhooks/config - Check
isActiveistrue - Ensure
endpoints.bookingsis set - 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 3000Then configure the webhook:
POST /v2/webhooks/config
{
"isActive": true,
"endpoints": {
"bookings": "https://abc123.ngrok.io/webhooks/bookings"
}
}Testing Checklist
- Endpoint returns
200 OKwithin 30 seconds - Handles duplicate events (same
EventId) - Checks the
X-Signatureheader - Fetches full booking details via API
- Processes all booking statuses correctly
- Updates your system appropriately
