Webhooks

Innkeeper's webhook system enables you to build event-driven integrations that react in real-time to changes in competitor hotel rates. This allows you to create dynamic, responsive applications that can automate decision-making based on market conditions.

Event-Driven Architecture#

Webhooks enable an event-driven architecture where:

• Your systems don't need to constantly poll our API for changes
• Actions are triggered immediately when relevant events occur
• You can build complex workflows and automations that respond to market changes
• Multiple systems can react to the same events independently

This approach is particularly valuable for hotels that need to maintain competitive pricing strategies with minimal manual intervention.

How Webhooks Work

The following diagram illustrates how our webhook system works:

┌─────────────────┐                                  ┌─────────────────┐
│                 │                                  │                 │
│   Booking.com   │                                  │   Your System   │
│   Price Change  │                                  │                 │
│                 │                                  │                 │
└────────┬────────┘                                  └────────▲────────┘
         │                                                    │
         │                                                    │
         │                                                    │ HTTP POST
         ▼                                                    │ (Webhook)
┌─────────────────┐    Detect     ┌─────────────────┐        │
│                 │    Changes    │                 │        │
│   Innkeeper     ├──────────────▶│   Innkeeper     │────────┘
│   Monitors      │               │   Event         │
│                 │               │   System        │────────┐
└─────────────────┘               └─────────────────┘        │
                                                             │ HTTP POST
                                                             │ (Webhook)
                                                             ▼
                                                   ┌─────────────────┐
                                                   │                 │
                                                   │  Another        │
                                                   │  System         │
                                                   │  (Optional)     │
                                                   └─────────────────┘

1. Innkeeper continuously monitors Booking.com for price changes
2. When a change is detected, it triggers an event in our system
3. Our event system sends HTTP POST requests (webhooks) to your configured endpoints
4. Your systems process these events and take automated actions

Competitor Rate Change Webhook#

Innkeeper sends POST requests to your configured webhook URL whenever a tracked competitor's rates change.

Configuration: Configure your webhook URL in your Innkeeper dashboard settings under "API & Integrations" → "Webhooks".

Webhook Payload:

{
  "event_id": "evt_123456789",
  "event_type": "competitor.rate.changed",
  "competitor_id": "comp_12345",
  "hotel_name": "Hotel California Downtown LA",
  "timestamp": "2025-04-11T15:04:05Z",
  "old_rate": 149.99,
  "new_rate": 139.99,
  "currency": "USD",
  "room_type": "Standard Queen Room"
}

Webhook Handling Best Practices#

1. Quick Acknowledgement: Respond to webhooks quickly (within 2 seconds) with a 200 OK status to acknowledge receipt. This prevents unnecessary retries.

2. Process Asynchronously: Handle complex processing outside of the initial webhook request. For example, queue the webhook data for processing and respond immediately.

3. Webhook Retries: Innkeeper will retry failed webhook deliveries up to 3 times with exponential backoff if your endpoint returns non-2xx status codes or times out.

4. Idempotency: All webhook events include a unique event_id to help you avoid processing duplicate events. Store processed event IDs to prevent double-handling if an event is received more than once.

5. Verification: Webhooks include a signature in the X-Innkeeper-Signature header that you should verify to ensure the webhook came from Innkeeper.

Verifying Webhook Signatures#

To verify that a webhook came from Innkeeper and not a third party:

1. Retrieve the X-Innkeeper-Signature header from the request
2. Use your webhook secret (found in your dashboard) to verify the signature
3. Compare the computed signature with the one in the header

Here's an example in Node.js:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

Create a Webhook Endpoint#

Payload:

{
  "url": "https://your-server.com/webhook",
  "description": "Rate change notifications",
  "events": ["competitor.rate.changed"]
}

Response (Success - 201):

{
  "id": "wh_123456",
  "url": "https://your-server.com/webhook",
  "description": "Rate change notifications",
  "events": ["competitor.rate.changed"],
  "secret": "whsec_abc123def456" 
}

Use Cases for Webhooks#

Some common use cases for Innkeeper's webhooks include:

• Dynamic Pricing: Automatically adjust your room rates based on competitor price changes
• Alerts and Notifications: Send alerts to your team when competitors drop prices significantly
• Market Analysis: Feed competitor rate changes into your analytics platform in real-time
• Custom Dashboards: Update live dashboards with the latest market positioning
• Automated Reporting: Generate reports when pricing thresholds are crossed