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
| Method | Description | Recommended For |
|---|---|---|
| Webhooks | Receive instant notification when the listing is accepted | Real-time integrations |
| Polling | Periodically call GET /v2/listings to check status | Simple 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
| Event | Description |
|---|---|
| Listing Created | Listing 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.
| Field | Type | Description |
|---|---|---|
EventId | UUID | Unique identifier for this event (use for idempotency) |
Timestamp | ISO 8601 | When we sent the event, in UTC |
BookingCode | null | Always null for listing events |
ListingId | integer | The accepted listing's ID |
EventType | null | Always null for listing events |
ConversationId | null | Always null for listing events |
MessageId | null | Always 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 OKwithin 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 reviewedPublished- Listing is live on Plum GuideHidden- Listing is not shown to guests (delisted)
Polling Recommendations:
- Poll every 24 hours
- Check the
statusfield 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
- Respond quickly - Return
200 OKimmediately, process asynchronously - Implement idempotency - Use
EventIdto avoid processing duplicates - Fetch full details - The webhook payload is minimal; use the API for complete data
- Handle retries - The same event may be delivered multiple times
Troubleshooting
Not receiving webhooks?
- Verify configuration:
GET /v2/webhooks/config - Check
isActiveistrue - Ensure
endpoints.listingsis set - 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);