> ## Documentation Index
> Fetch the complete documentation index at: https://developer.meetergo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time notifications when booking events occur

Webhooks let you receive HTTP POST requests when events happen in meetergo. Use them to sync bookings with your CRM, trigger workflows, or update your application in real-time.

## How Webhooks Work

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant meetergo
    participant Your Server

    Customer->>meetergo: Books appointment
    meetergo->>meetergo: Creates booking
    meetergo->>Your Server: POST webhook (booking_created)
    Your Server-->>meetergo: 200 OK
    meetergo->>Customer: Confirmation email
```

When an event occurs (booking created, cancelled, rescheduled, form submitted), meetergo sends an HTTP POST request to your configured endpoint with event details.

## Available Events

| Event                 | Trigger                                                           |
| --------------------- | ----------------------------------------------------------------- |
| `booking_created`     | New appointment is booked                                         |
| `booking_cancelled`   | Appointment is cancelled (or attendee removed from group booking) |
| `booking_rescheduled` | Appointment time is changed                                       |
| `new_employee`        | New user is added to your company                                 |
| `form_submission`     | Routing form or funnel is submitted                               |

## Quick Setup

1. **Create a webhook endpoint** on your server that accepts POST requests
2. **Register the endpoint** via the API or dashboard
3. **Handle incoming events** and return a 200 response

### Example Endpoint (Node.js/Express)

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/meetergo', (req, res) => {
  const payload = req.body;

  console.log('Received event:', payload.webhookType);

  // Process the event based on webhookType
  switch (payload.webhookType) {
    case 'booking_created':
      handleNewBooking(payload);
      break;
    case 'booking_cancelled':
      handleCancellation(payload);
      break;
    case 'booking_rescheduled':
      handleReschedule(payload);
      break;
    case 'form_submission':
      handleFormSubmission(payload);
      break;
  }

  // Always return 200 quickly
  res.status(200).send('OK');
});

app.listen(3000);
```

### Example Endpoint (Python/Flask)

```python theme={null}
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/meetergo', methods=['POST'])
def handle_webhook():
    payload = request.json

    print(f"Received event: {payload['webhookType']}")

    if payload['webhookType'] == 'booking_created':
        handle_new_booking(payload)
    elif payload['webhookType'] == 'booking_cancelled':
        handle_cancellation(payload)
    elif payload['webhookType'] == 'booking_rescheduled':
        handle_reschedule(payload)
    elif payload['webhookType'] == 'form_submission':
        handle_form_submission(payload)

    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)
```

## Webhook Payload Structure

All webhook payloads include a `webhookType` field identifying the event, with the rest of the event-specific data at the top level:

```json theme={null}
{
  "webhookType": "booking_created",
  "id": "appt-uuid-12345",
  "start": "2024-01-15T09:00:00+01:00",
  "end": "2024-01-15T09:30:00+01:00",
  // ... remaining event-specific fields
}
```

## Limits

| Limit                | Value      |
| -------------------- | ---------- |
| Webhooks per company | 6          |
| Request timeout      | 30 seconds |
| Payload size         | \~100KB    |

## Best Practices

<Check>
  **Return 200 quickly** - Process webhooks asynchronously to avoid timeouts
</Check>

<Check>
  **Use HTTPS** - Always use secure endpoints in production
</Check>

<Check>
  **Handle duplicates** - Webhooks may be delivered more than once; use idempotent processing
</Check>

<Check>
  **Log everything** - Keep webhook logs for debugging
</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Event Reference" icon="list" href="/developer-docs/webhooks/events">
    Detailed payload documentation for each event
  </Card>

  <Card title="Managing Webhooks" icon="gear" href="/developer-docs/webhooks/managing-webhooks">
    Create, update, and delete webhooks via API
  </Card>
</CardGroup>