Managing Webhooks

Manage your webhook endpoints programmatically using the Webhooks API.

Create a Webhook

curl -X POST "https://api.meetergo.com/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: {userId}" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://your-server.com/webhooks/meetergo",
    "description": "Production webhook",
    "eventTypes": ["booking_created", "booking_cancelled", "booking_rescheduled"]
  }'

const response = await fetch('https://api.meetergo.com/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-meetergo-api-user-id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    endpoint: 'https://your-server.com/webhooks/meetergo',
    description: 'Production webhook',
    eventTypes: ['booking_created', 'booking_cancelled', 'booking_rescheduled']
  })
});

import requests

response = requests.post(
    'https://api.meetergo.com/webhooks',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'x-meetergo-api-user-id': user_id,
        'Content-Type': 'application/json'
    },
    json={
        'endpoint': 'https://your-server.com/webhooks/meetergo',
        'description': 'Production webhook',
        'eventTypes': ['booking_created', 'booking_cancelled', 'booking_rescheduled']
    }
)

Request Body

Field	Type	Required	Description
`endpoint`	string	Yes	URL to receive webhook POST requests
`description`	string	No	Human-readable description
`eventTypes`	string[]	Yes	Events to subscribe to

Event Types

Value	Description
`booking_created`	New appointment booked
`booking_cancelled`	Appointment cancelled (or attendee removed from group booking)
`booking_rescheduled`	Appointment time changed
`new_employee`	New user added to company
`form_submission`	Routing form or funnel submitted

Response

{
  "id": "webhook-uuid-123",
  "endpoint": "https://your-server.com/webhooks/meetergo",
  "description": "Production webhook",
  "eventTypes": ["booking_created", "booking_cancelled", "booking_rescheduled"],
  "companyId": "company-uuid-789",
  "createdAt": "2024-01-15T10:00:00Z"
}

List Webhooks

Get all webhooks for your company:

curl -X GET "https://api.meetergo.com/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: {userId}"

Response

[
  {
    "id": "webhook-uuid-123",
    "endpoint": "https://your-server.com/webhooks/meetergo",
    "description": "Production webhook",
    "eventTypes": ["booking_created", "booking_cancelled"],
    "companyId": "company-uuid-789",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  {
    "id": "webhook-uuid-456",
    "endpoint": "https://staging.your-server.com/webhooks/meetergo",
    "description": "Staging webhook",
    "eventTypes": ["booking_created"],
    "companyId": "company-uuid-789",
    "createdAt": "2024-01-14T09:00:00Z"
  }
]

Update a Webhook

Modify an existing webhook:

curl -X PATCH "https://api.meetergo.com/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: {userId}" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypes": ["booking_created", "booking_cancelled", "booking_rescheduled", "new_employee"]
  }'

Request Body

All fields are optional:

Field	Type	Description
`endpoint`	string	New endpoint URL
`description`	string	New description
`eventTypes`	string[]	New event subscriptions

Delete a Webhook

Remove a webhook endpoint:

curl -X DELETE "https://api.meetergo.com/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: {userId}"

Returns 204 No Content on success.

Limits

Limit	Value
Maximum webhooks per company	6
Minimum event types per webhook	1

Error: Maximum Webhooks Reached

{
  "statusCode": 406,
  "message": "Company reached maximum",
  "error": "Not Acceptable"
}

Solution: Delete unused webhooks before creating new ones.

Testing Webhooks

Local Development

Use a tunneling service for local development: ngrok

ngrok http 3000
# Returns: https://abc123.ngrok.io

localtunnel

npx localtunnel --port 3000
# Returns: https://your-subdomain.loca.lt

Test with curl

Simulate a webhook delivery to your endpoint:

curl -X POST "https://your-server.com/webhooks/meetergo" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookType": "booking_created",
    "id": "test-appt-123",
    "start": "2024-01-15T09:00:00+01:00",
    "end": "2024-01-15T09:30:00+01:00",
    "attendees": [{
      "email": "test@example.com",
      "firstname": "Test",
      "lastname": "User"
    }],
    "hosts": [{
      "email": "host@example.com",
      "givenName": "Host",
      "familyName": "User"
    }],
    "meetingType": {
      "id": "mt-123",
      "meetingInfo": { "name": "Test Meeting" }
    }
  }'

Webhook Reliability

Delivery Guarantees

Webhooks are delivered at least once
Failed deliveries are not automatically retried
Implement idempotent handlers using the appointment id

Handling Failures

Your endpoint should:

Return 200 quickly - Process asynchronously if needed
Be idempotent - Same webhook delivered twice should have same result
Log all requests - For debugging failed deliveries

Example: Idempotent Handler

const processedEvents = new Set();

app.post('/webhooks/meetergo', async (req, res) => {
  const payload = req.body;
  const eventKey = `${payload.webhookType}:${payload.id || payload.formId}:${payload.updatedAt || payload.submittedAt}`;

  // Return 200 immediately
  res.status(200).send('OK');

  // Skip if already processed
  if (processedEvents.has(eventKey)) {
    console.log('Duplicate event, skipping:', eventKey);
    return;
  }

  processedEvents.add(eventKey);

  // Process asynchronously
  try {
    await processEvent(payload.webhookType, payload);
  } catch (error) {
    console.error('Failed to process webhook:', error);
    // Add to retry queue
    await retryQueue.add(payload);
  }
});

Best Practices

Use HTTPS - All production webhook endpoints should use HTTPS

Return 200 immediately - Don’t block the response while processing

Implement idempotency - Handle duplicate deliveries gracefully

Log requests - Keep logs for debugging

Monitor failures - Alert when webhook processing fails

Don’t expose secrets - Never include API keys or secrets in webhook endpoint URLs

Get Started

Core Concepts

Webhooks

Components

Recipes

Best Practices

Managing Webhooks

Create a Webhook

Request Body

Event Types

Response

List Webhooks

Response

Update a Webhook

Request Body

Delete a Webhook

Limits

Error: Maximum Webhooks Reached

Testing Webhooks

Local Development

Test with curl

Webhook Reliability

Delivery Guarantees

Handling Failures

Example: Idempotent Handler

Best Practices

​Create a Webhook

​Request Body

​Event Types

​Response

​List Webhooks

​Response

​Update a Webhook

​Request Body

​Delete a Webhook

​Limits

​Error: Maximum Webhooks Reached

​Testing Webhooks

​Local Development

​Test with curl

​Webhook Reliability

​Delivery Guarantees

​Handling Failures

​Example: Idempotent Handler

​Best Practices

Create a Webhook

Request Body

Event Types

Response

List Webhooks

Response

Update a Webhook

Request Body

Delete a Webhook

Limits

Error: Maximum Webhooks Reached

Testing Webhooks

Local Development

Test with curl

Webhook Reliability

Delivery Guarantees

Handling Failures

Example: Idempotent Handler

Best Practices