🗄️ Synchronize Data

Track lifecycle events to keep your data synchronized

What Data Can Be Synchronized?

The platform emits business events whenever key data changes. By subscribing to these events, you can maintain synchronized copies of platform data in your own systems, databases, or data warehouses.

Synchronizable Data Types:

Object	Key Lifecycle Events
Booking	CREATED, UPDATED, IBE_SUCCESS, IBE_FAILED
Reservation	CREATED, UPDATED, CHECKED_IN, CHECKED_OUT, CANCELLED, NO_SHOW, CONDITION_UPDATED
Folio	CREATED, UPDATED
Profile	CREATED, UPDATED, LANGUAGE_UPDATED, MERGED
Task	CREATED, UPDATED, COMPLETED
Unit	CREATED, UPDATED

Why Synchronize Data?

Real-time event-driven synchronization offers significant advantages over polling:

✅ Instant updates - Data changes propagate immediately, not on polling intervals
✅ Reduce API load - No need to repeatedly query for changes
✅ Single source of truth - Platform remains the authoritative source
✅ Enable offline capabilities - Local data copy for offline scenarios
✅ Analytics & reporting - Historical data for business intelligence
✅ System decoupling - Independent systems stay in sync without tight coupling

Understand the Event Structure

All events follow a standardized structure. For the complete event model and enumerations, see Business Event Model.

Synchronize Data Flow

sequenceDiagram
    participant Client as Your Application
    participant Webhook as LIKE MAGIC Webhook Publisher
    participant API as LIKE MAGIC Open API / PMS Open API

    Note over Webhook: Event occurs in platform<br/>(e.g., PROFILE_UPDATED)
    Webhook->>Client: POST /webhook/endpoint<br/>Event payload (JSON)
    Client->>Client: Validate event<br/>(check event ID for duplicates)
    Client-->>Webhook: 200 OK
    Note over Webhook: Event delivery confirmed

    opt Fetch additional details
        Client->>API: GET /profiles/{id}
        API-->>Client: Complete profile data
    end

    Client->>Client: Process event<br/>(merge event + full data)
    Client->>Client: Update local database<br/>(upsert record)

Topic-Level Subscriptions

Webhook subscriptions operate at the topic level, allowing you to:

• Subscribe to specific event types - Choose exactly which topics interest your integration
• Reduce noise - Process only relevant events
• Scale efficiently - Route different topics to different endpoints
• Maintain flexibility - Add or remove topic subscriptions as requirements evolve

Example Subscription Patterns

// Guest management system
['RESERVATION_CREATED', 'RESERVATION_UPDATED', 'RESERVATION_CHECKED_IN']

// Housekeeping integration
['TASK_CREATED', 'TASK_UPDATED', 'TASK_COMPLETED']

Important: Event Delivery Order

⚠️ Events are not guaranteed to be delivered in chronological order.

Due to our distributed infrastructure:

• Events may arrive out of sequence
• Events with earlier timestamps may arrive after events with later timestamps
• Multiple events for the same object may arrive in any order

Handling Out-of-Order Events

// Example: Track latest event by timestamp
class EventProcessor {
  constructor() {
    this.lastProcessedTimestamp = {};
  }

  async processEvent(event) {
    const key = `${event.object}-${event.objectId}`;
    const lastTimestamp = this.lastProcessedTimestamp[key];

    // Only process if this event is newer
    if (!lastTimestamp || new Date(event.timestamp) > new Date(lastTimestamp)) {
      await this.handleEvent(event);
      this.lastProcessedTimestamp[key] = event.timestamp;
    } else {
      console.log(`Skipping out-of-order event ${event.id}`);
    }
  }
}

Best practices:

1. Use timestamps - Rely on the timestamp field rather than arrival time
2. Implement idempotency - Handle duplicate or out-of-order events safely
3. Store state - Maintain current state and update based on timestamp comparison
4. Event sourcing - Consider event sourcing patterns if strict ordering is critical

Available Buiness Events

For detailed event specifications and context fields, see the Business Event Documentation.

Webhook Endpoint Requirements

Your webhook endpoint must:

1. Accept POST requests with JSON payload
2. Return 200 OK within 5 seconds
3. Support HTTPS with a valid SSL certificate
4. Be publicly accessible (not localhost or internal network)

Example Webhook Consumer

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/likemagic', async (req, res) => {
  const event = req.body;
  const secret = req.headers['lm-webhook-secret'];

  // 1. Verify secret
  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  // 2. Return 200 immediately
  res.status(200).send('OK');

  // 3. Process asynchronously
  processEventAsync(event).catch(err => {
    console.error('Error processing event:', err);
  });
});

async function processEventAsync(event) {
  // Check for duplicate
  if (await isDuplicate(event.id)) {
    console.log(`Duplicate event ${event.id}, skipping`);
    return;
  }

  // Process based on topic
  switch (event.topic) {
    case 'RESERVATION_CHECKED_IN':
      await handleCheckin(event);
      break;
    case 'TASK_COMPLETED':
      await handleTaskCompletion(event);
      break;
    // ... handle other topics
  }

  // Mark as processed
  await markProcessed(event.id);
}

Retry Policy

Failed webhook deliveries are automatically retried with exponential backoff. The system performs up to 15 delivery attempts before moving events to a dead letter queue.

For complete details on retry behavior, automatic subscription deactivation and recovery procedures, see the Webhook Retry Documentation.

Best Practices

Event Processing

1. Idempotency: Always handle events idempotently using the event id field
2. Async Processing: Process events asynchronously to quickly return 200 OK
3. Order Independence: Use the timestamp field, not arrival order
4. Failure Handling: Implement proper error handling and logging
5. State Management: Store and compare timestamps to handle out-of-order events

Security

1. Verify Signatures: Validate the lm-webhook-secret header matches your configured secret
2. Use HTTPS: Ensure your endpoint uses HTTPS
3. Store Secrets Securely: Use environment variables or secret managers
4. Rotate Secrets: Regenerate secrets if compromised

Monitoring

1. Log all events: Keep audit trail of received events
2. Track processing time: Monitor event processing duration
3. Alert on failures: Set up alerts for repeated failures
4. Monitor duplicate rate: Track duplicate event frequency

Related Documentation

• Business Events Overview - Complete event catalog
• Manage Webhook Subscriptions - How to subscribe to events
• Webhook Retry Policy - Delivery guarantees and retry behavior
• Event and Data Hub API - Fetch historical events and profile data

---

Ready to start syncing? Subscribe to lifecycle events and maintain real-time data consistency across your systems.