Webhooks

Webhooks allow your application to receive real-time notifications about specific events occurring within the Bookla platform. This guide explains how to set up and manage webhooks for your integration.

Key Concepts

• Endpoint: A URL where Bookla will send HTTP POST requests when specific events occur.
• Subscription: A configuration that defines which events will trigger notifications to a specific endpoint.

Setting Up Webhooks

The process of setting up webhooks in Bookla involves two main steps: creating an endpoint and adding subscriptions to that endpoint.

Step 1: Creating an Endpoint

1. Navigate to the Developers section in your Bookla Developer Dashboard.
2. Select the "Webhooks" tab.
3. Click on "Add New Endpoint".
4. Provide the following information:

• Name: A descriptive name for the endpoint (e.g., "Production Booking Notifications")
• URL: The full URL where Bookla will send webhook events (e.g., https://api.yourdomain.com/bookla-webhooks)

5. Click "Create Endpoint".

Step 2: Adding Subscriptions

After creating an endpoint, you need to specify which events you want to receive at that endpoint.

1. Find your newly created endpoint in the list and click "Add Subscription".
2. Provide a name for the subscription (e.g., "New Bookings").
3. Select the events you want to subscribe to. Common events include:

• Booking created
• Booking updated
• Service created
• Resource updated
• And more

4. Click "Create Subscription".

You can add multiple subscriptions to a single endpoint, allowing you to organize your event handling logically.

Handling Webhook Events

When an event occurs, Bookla will send an HTTP POST request to your specified endpoint URL. The request body will contain a JSON payload with details about the event.

Example payload:

{
    id: "ev_bd17c1d0-f4a1-4523-a11a-f5c166ee807c",
    data: {
        id: "f690d976-9d7e-4054-a0c3-483a1f2e1ca5",
        name: "Tennis court",
        color: "#CFC4E8",
        companyID: "efa6070b-861c-4baa-972d-1c0cf925426f",
        createdAt: "2024-07-07T16:02:05Z",
        updatedAt: "2024-07-07T16:02:05Z"
    },
    type: "event.gateway.resource.created",
    createdAt: "2024-07-07T16:02:05Z"
}

Your server should:

1. Respond quickly with a 2xx status code.
2. Process the event asynchronously if it requires time-consuming operations.

Best Practices

1. Handle Retries: Bookla may retry failed webhook deliveries. Implement idempotency to handle potential duplicate events.
2. Monitor Webhook Health: Implement logging and alerting for webhook reception and processing.
3. Use HTTPS: Ensure your endpoint uses HTTPS to keep the data secure in transit.
4. Implement Queue Processing: For high-volume webhooks, consider using a queue system to manage incoming webhook events.

Testing Webhooks

1. Use a tool like webhook.site for initial testing and debugging.
2. Implement a development endpoint that logs all received payloads for easier debugging.

Troubleshooting

• Check your server logs if you're not receiving expected webhooks.
• Verify that your firewall isn't blocking incoming requests from Bookla's IP ranges.
• Ensure your endpoint is responding with a 2xx status code within the required timeframe.
• List of IP ranges used by Bookla for webhook delivery:
  • 139.59.139.87

API Reference

For detailed information on available webhook events and payload structures, refer to the Webhooks API Documentation.

By following this guide, you can effectively set up and manage webhooks in your Bookla integration, enabling real-time updates and improving the responsiveness of your application.