Skip to content

👂 Listening on Events

React instantly to platform activity

Why Listen to Events?

Listen to business events to automate workflows and trigger real-time actions without polling or manual intervention.

Common Use Cases:

✅ Send notifications - Email guests when reservations are confirmed or checked in
✅ Trigger automations - Start workflows when tasks are created or completed
✅ Log activity - Track important events in external systems
✅ Call external APIs - Notify third-party services of platform changes
✅ Alert teams - Send Slack/Teams messages for critical events

Event Flow

sequenceDiagram
    participant Client as Your Application
    participant Webhook as LIKE MAGIC Webhook Publisher

    Note over Webhook: Event occurs in platform<br/>(e.g., RESERVATION_CHECKED_IN)
    Webhook->>Client: POST /webhook/endpoint<br/>Event payload (JSON)
    Client->>Client: Validate event
    Client-->>Webhook: 200 OK
    Note over Client: Process asynchronously
    Client->>Client: React to event<br/>(send email, call API, trigger workflow)

Available Events

By subscribing to specific event topics, you receive real-time notifications when those events occur. Browse all available events in the Business Events documentation.

Event Structure

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

Simple Webhook Example

Here's a basic webhook endpoint that reacts to events:

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. React to event asynchronously
  reactToEvent(event).catch(err => {
    console.error('Error reacting to event:', err);
  });
});

async function reactToEvent(event) {
  console.log(`Received ${event.topic} for ${event.objectId}`);

  switch (event.topic) {
    case 'RESERVATION_CHECKED_IN':
      await sendWelcomeEmail(event);
      break;

    case 'TASK_COMPLETED':
      await notifySlack(`Task ${event.objectId} completed!`);
      break;

    case 'MESSAGE_RECEIVED':
      await alertSupportTeam(event);
      break;

    default:
      console.log(`No handler for ${event.topic}`);
  }
}

async function sendWelcomeEmail(event) {
  const { guestName, roomNumber } = event.context;
  // Send email via your email service
  console.log(`Sending welcome email to guest in room ${roomNumber}`);
}

async function notifySlack(message) {
  // Post to Slack webhook
  console.log(`Slack notification: ${message}`);
}

async function alertSupportTeam(event) {
  // Notify support team of new message
  console.log(`New message from guest: ${event.objectId}`);
}

Common Reaction Patterns

Send Notifications

case 'RESERVATION_CREATED':
  await emailService.send({
    to: event.context.guestEmail,
    subject: 'Booking Confirmed',
    template: 'booking-confirmation',
    data: event.context
  });
  break;

Trigger Workflows

case 'TASK_CREATED':
  await workflowEngine.trigger({
    workflow: 'assign-housekeeping-task',
    data: {
      taskId: event.objectId,
      unitId: event.context.unitId
    }
  });
  break;

Call External APIs

case 'PROFILE_UPDATED':
  await crmApi.updateContact({
    id: event.objectId,
    updates: event.context
  });
  break;

Log Events

case 'RESERVATION_CHECKED_IN':
  await logger.info({
    event: 'checkin',
    reservationId: event.objectId,
    timestamp: event.timestamp,
    details: event.context
  });
  break;

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)

💡 Important: Always return 200 OK quickly, then process events asynchronously.

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, see the Webhook Retry Documentation.

Best Practices

Event Processing

  1. Return 200 OK immediately - Process events asynchronously
  2. Handle duplicates - Check event IDs to prevent duplicate processing
  3. Log events - Keep track of received events for debugging
  4. Error handling - Use try-catch blocks and log errors

Security

  1. Verify webhook secret - Always validate the lm-webhook-secret header
  2. Use HTTPS - Ensure your endpoint uses HTTPS
  3. Store secrets securely - Use environment variables

Monitoring

  1. Log all events - Track what events you receive
  2. Alert on failures - Monitor for processing errors
  3. Track processing time - Ensure reactions complete quickly

Ready to automate? Subscribe to events and start reacting to platform activity in real-time.