Webhooks

Webhooks allow you to receive real-time notifications when events happen on your Luma calendar—like when a guest registers, an event is created, or a ticket is purchased. Instead of polling the API, webhooks push data to your server as soon as events occur.

Webhooks are only available for Luma Plus subscribers. Find out more about Luma Plus here.

Creating a Webhook

1. Visit the Calendars Home and select your calendar
2. Navigate to Settings → Developer
3. In the Webhooks section, click Create
4. Enter your webhook URL
5. Select which action types you want to receive (or choose "All Actions")
6. Click Create to save

Available Event Types

Calendar & Audience

• Calendar Event Added - Triggered when any event appears on your calendar, including events managed by the calendar, events syndicated from other calendars, and external events you've added.
• Calendar Person Subscribed - Triggered when someone subscribes to your calendar.

Events

• Event Created - Triggered when a new event is created on your calendar.
• Event Updated - Triggered when event details are modified (title, date, location, etc.). Does not trigger for guest registrations.
• Event Canceled - Triggered when an event is canceled.

Guests & Registrations

• Guest Registered - Triggered when someone registers for an event for the first time. Perfect for welcome emails and initial confirmations.
• Guest Updated - Triggered when a guest registers and whenever guest information changes (check-in status, approval status, profile updates). Note: This fires for both new registrations and updates to existing guests.

Tickets

• Ticket Registered - Triggered for each individual ticket purchase. If a guest buys 3 tickets, this triggers 3 times, allowing you to track individual ticket sales and create unique experiences per ticket.

Understanding Guest vs Ticket Events

Use Guest Registered when you want to trigger once per person registering—for example, to send a welcome email. Use Ticket Registered when you need to track each individual ticket—for example, if you want to generate a unique QR code or badge for every ticket purchased.

Webhook Payloads

Webhook payloads include a type field indicating the event type and a data object with the relevant information. For detailed payload schemas and field descriptions, see the API documentation.

Managing Webhooks

You can manage your webhooks from Settings → Developer:

• View deliveries - Click on a webhook to see recent delivery attempts and their status (delivered, pending, or failed)
• Pause and resume - Temporarily pause a webhook if you need to stop receiving events, then resume when ready
• Delete - Remove webhooks you no longer need

Retry Behavior

If your webhook endpoint fails to respond or returns an error, Luma will automatically retry delivery:

• Up to 3 retry attempts
• Retries occur with exponential backoff (1 minute, 2 minutes, then 4 minutes)
• If your endpoint returns a 410 Gone status, the webhook will be automatically paused

Best Practices

• Respond quickly - Your endpoint should respond within 5 seconds
• Return success codes - Return a 2xx status code to indicate successful receipt
• Handle duplicates - In rare cases, you may receive the same event more than once—design your system to handle this gracefully

Troubleshooting

If your webhooks aren't working as expected:

• Check delivery status - View recent deliveries in the webhook panel to see if events are being sent and whether they're succeeding or failing
• Verify your endpoint - Make sure your webhook URL is publicly accessible
• Check your server logs - Look for any errors in how your server is processing incoming webhooks