Webhooks Guide - RoostSync

Overview

Webhooks allow RoostSync to notify your external systems in real-time when events occur. Instead of polling the API, receive instant notifications when bookings are created, guests check in, orders are placed, and more.

Webhooks Coming Soon

We are finalizing the webhooks system. Below is a preview of planned functionality. Check back for the full release!

How Webhooks Work

You register a URL endpoint to receive notifications
An event occurs in RoostSync (e.g., new booking)
RoostSync sends an HTTP POST to your URL
Your system processes the notification
You respond with 200 OK to acknowledge receipt

Planned Webhook Events

Event	Trigger
`booking.created`	New booking is created
`booking.updated`	Booking details are modified
`booking.cancelled`	Booking is cancelled
`guest.checkin`	Guest checks in
`guest.checkout`	Guest checks out
`order.created`	POS order is placed
`order.completed`	Order is paid and completed
`inventory.low`	Item falls below reorder level
`payment.received`	Payment is processed

Webhook Payload (Preview)

Example payload for a booking.created event:

{
  "event": "booking.created",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "booking_id": "bk_12345",
    "guest_name": "Juan dela Cruz",
    "room": {
      "id": "rm_101",
      "name": "Room 101 - Deluxe"
    },
    "check_in": "2024-03-20",
    "check_out": "2024-03-22",
    "nights": 2,
    "total": 6000,
    "source": "direct",
    "status": "confirmed"
  },
  "property_id": "prop_abc123"
}

Setting Up Webhooks

When available, you will be able to configure webhooks in Settings > Integrations > Webhooks:

1. Add Webhook Endpoint

Enter your endpoint URL (must be HTTPS)
Select events to subscribe to
Add optional description

2. Configure Security

Generate a signing secret
Use secret to verify webhook authenticity
Optionally set custom headers

3. Test Your Endpoint

Send test webhook to verify setup
Check your endpoint receives and processes correctly
Enable the webhook when ready

Verifying Webhooks

Each webhook will include a signature header for verification:

X-RoostSync-Signature: sha256=abc123...

// Verification example (Node.js)
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Best Practices

Respond quickly - Return 200 OK immediately, process async
Handle duplicates - Same event may be sent multiple times
Verify signatures - Always validate webhook authenticity
Use HTTPS - Required for security
Log everything - Keep records for debugging
Implement retries - Handle temporary failures gracefully

Retry Policy

If your endpoint fails to respond, we will retry:

Retry 1: After 1 minute
Retry 2: After 5 minutes
Retry 3: After 30 minutes
Retry 4: After 2 hours
Retry 5: After 24 hours

After 5 failed attempts, the webhook will be marked as failing and you will be notified.

Important

Your endpoint must respond within 30 seconds. For longer processing, acknowledge receipt immediately and handle processing asynchronously.

Use Cases

Sync with accounting - Push new payments to your accounting system
Send notifications - Trigger SMS/email via your preferred service
Update external calendars - Sync bookings to other platforms
Custom dashboards - Feed real-time data to your displays
Inventory alerts - Notify purchasing when items run low

Coming Soon

We are also planning a webhook testing tool in the dashboard where you can view recent webhook deliveries, payloads, and responses for debugging.

Request Early Access

Interested in early access to webhooks? Contact us:

Email: api@roostsync.com
Subject: Webhooks Early Access Request
Include: Your use case and which events you need

API Reference Back to Docs