Subscriptions (Webhooks)

The Lighthouse API uses a subscription mechanism to notify third-party integrations in real-time when various events are triggered by Lighthouse components.

Overview

Subscriptions (webhooks) provide event-driven integration with the Lighthouse system. Instead of continuously polling the API for changes, your application receives HTTP POST notifications when relevant events occur.

How Subscriptions Work

1. Register Your Endpoint - Provide a webhook URL that your application maintains
2. Receive Events - Lighthouse sends POST requests to your endpoint when events occur
3. Authenticate Requests - Verify each webhook using HMAC signature validation
4. Parse and Process - Extract event data from the JSON payload and take action

Key Benefits

• Real-Time Updates - Receive notifications instantly when events occur
• Reduced API Calls - Eliminate constant polling, reducing rate limit usage
• Event-Driven Architecture - Build reactive integrations that respond to changes
• Reliable Delivery - Lighthouse retries failed webhook deliveries automatically

Authentication

HMAC Signature Validation

Every webhook request includes HMAC authentication headers that you must validate to ensure the request originated from Lighthouse:

Validating Webhook Signatures

To verify a webhook request is authentic, generate your own signature and compare it to the x-signature header.

Example Credentials:

• client_id: 23b08412a29bbe8625967e16c1a41dc9
• client_secret: de17f1f0-4816-157b-97ae-eb4b0f656a1f

Signature Validation Steps

23b08412a29bbe8625967e16c1a41dc9POST/subscriptions/order{"event":{...},"payload":{...}}1554456360

const crypto = require('crypto');

function validateWebhook(request) {
  const CLIENT_ID = '23b08412a29bbe8625967e16c1a41dc9';
  const CLIENT_SECRET = 'de17f1f0-4816-157b-97ae-eb4b0f656a1f';

  // Extract headers
  const receivedSignature = request.headers['x-signature'];
  const timestamp = request.headers['x-timestamp'];
  const accessKey = request.headers['x-access-key'];

  // Verify client ID matches
  if (accessKey !== CLIENT_ID) {
    return false;
  }

  // Extract path from request URL
  const urlPath = new URL(request.url).pathname;

  // Get raw request body
  const requestBody = JSON.stringify(request.body);

  // Combine components
  const combinedString =
    CLIENT_ID +
    'POST' +
    urlPath +
    requestBody +
    timestamp;

  // Generate signature
  const hmac = crypto.createHmac('sha256', CLIENT_SECRET);
  hmac.update(combinedString);
  const calculatedSignature = hmac.digest('hex');

  // Compare signatures
  return calculatedSignature === receivedSignature;
}

Event Structure

Webhook Request Format

All webhook notifications are sent as POST requests with JSON payloads containing two main sections: event metadata and payload data.

{
  "event": {
    "component": "online-ordering",
    "resource": "Menu",
    "action": "updated",
    "name": "online-ordering.Menu.updated",
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "locationId": 1
  }
}

Event Metadata

Event Payload

The payload object contains resource-specific data related to the event. The structure varies based on the component, resource, and action.

Note: Subscription payload structure depends on the specific event type. Refer to the endpoint documentation for detailed payload schemas.

Event Types

Common Event Patterns

Webhook events follow consistent naming patterns across different components:

Example Event Handlers

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

app.post('/webhooks/lighthouse', express.json(), (req, res) => {
  // Validate signature first
  if (!validateWebhook(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, payload } = req.body;

  // Route to appropriate handler based on event name
  switch (event.name) {
    case 'online-ordering.Order.created':
      handleNewOrder(payload);
      break;

    case 'online-ordering.Order.updated':
      handleOrderUpdate(payload);
      break;

    case 'pos.Check.updated':
      handleCheckUpdate(payload);
      break;

    case 'marketplace.Installation.created':
      handleNewInstallation(payload);
      break;

    default:
      console.log(`Unhandled event: ${event.name}`);
  }

  // Always respond with 200 OK quickly
  res.status(200).json({ received: true });
});

function handleNewOrder(payload) {
  console.log('New order received:', payload);
  // Process order asynchronously
}

function handleOrderUpdate(payload) {
  console.log('Order updated:', payload);
  // Update order status in your system
}

function handleCheckUpdate(payload) {
  console.log('Check updated:', payload);
  // Sync check data
}

function handleNewInstallation(payload) {
  console.log('New installation:', payload);
  // Initialize integration for location
}

Best Practices

Webhook Endpoint Requirements

Technical Requirements

Your webhook endpoint must:

• Accept POST Requests - All webhooks are sent via HTTP POST
• Support HTTPS - Production webhooks require SSL/TLS
• Validate Signatures - Check HMAC signature on every request
• Respond Quickly - Return 2xx status within 5 seconds
• Handle JSON - Parse application/json content type
• Be Publicly Accessible - Reachable from Lighthouse servers

Response Codes

Retry Behavior

When webhook delivery fails, Lighthouse implements exponential backoff:

1. First retry: After 1 minute
2. Second retry: After 5 minutes
3. Third retry: After 15 minutes
4. Additional retries: Up to 24 hours

After maximum retries, the event is marked as failed and logged for manual review.

Setting Up Subscriptions

To configure webhooks for your integration:

1. Prepare Your Endpoint - Deploy a webhook handler that validates signatures and returns 200 OK
2. Test Locally - Use tools like ngrok to test webhook handling during development
3. Contact Shift4 Support - Provide your webhook URL and desired event types
4. Configure Subscriptions - Support will configure subscriptions in your integration profile
5. Monitor Initial Deliveries - Watch logs for first events and verify signature validation works
6. Go Live - Once tested, deploy to production and update subscription URL

For assistance with webhook configuration, contact Shift4 integration support with your integration details and webhook requirements.