Listings Webhooks

This guide explains how to receive real-time notifications when listings are accepted on the Plum Guide platform.

Overview

When a listing passes Plum Guide's review process and is accepted onto the platform, you can be notified via webhook. This eliminates the need to poll the API for listing status updates.

Options for Tracking Listing Status

MethodDescriptionRecommended For
WebhooksReceive instant notification when the listing is acceptedReal-time integrations
PollingPeriodically call GET /v2/listings to check statusSimple integrations

Quick Start

1. Configure Listings Webhook Endpoint

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

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

2. Receive Listing Created Events

When a listing is accepted, your endpoint receives:

{
  "EventId": "660e8400-e29b-41d4-a716-446655440001",
  "Timestamp": "2025-01-15T11:00:00.0000000Z",
  "BookingCode": null,
  "ListingId": 12345,
  "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 Listing Details

Use the listing ID to get full details:

GET /v2/listing/{listingId}
Authorization: Bearer {your_token}

Listing Events

EventDescription
Listing CreatedListing has been accepted and published on Plum Guide

Webhook Payload

{
  "EventId": "660e8400-e29b-41d4-a716-446655440001",
  "Timestamp": "2025-01-15T11:00:00.0000000Z",
  "BookingCode": null,
  "ListingId": 12345,
  "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
BookingCodenullAlways null for listing events
ListingIdintegerThe accepted listing's ID
EventTypenullAlways null for listing events
ConversationIdnullAlways null for listing events
MessageIdnullAlways null for listing events

Every webhook carries the header X-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body keyed with your signingSecret. See Bookings Webhooks for how to check it.


Configuration API

Create

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

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

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

Alternative: Polling

If you prefer not to use webhooks, you can poll the listings endpoint:

GET /v2/listings
Authorization: Bearer {your_token}

This returns all listings for your account with their current status:

  • InReview - Listing is being reviewed
  • Published - Listing is live on Plum Guide
  • Hidden - Listing is not shown to guests (delisted)

Polling Recommendations:

  • Poll every 24 hours
  • Check the status field for changes
  • Store last known status to detect changes

Example Handler

app.post('/webhooks/listings', async (req, res) => {
  const { EventId: eventId, ListingId: listingId } = req.body;

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

  // Fetch full listing details
  const listing = await plumApi.getListing(listingId);

  // Handle the accepted listing
  console.log(`Listing ${listingId} accepted: ${listing.listingName}`);

  // Update your system
  await updateListingStatus(listingId, 'published');
});

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 is minimal; use the API for complete data
  4. Handle retries - The same event may be delivered multiple times

Troubleshooting

Not receiving webhooks?

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

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);