Webhooks API

Configure and manage webhook endpoints for real-time event notifications.

POST /api/v1/platform/webhooks

Requires API authentication

Request Body

{
  "url": "https://your-app.com/webhooks/vardacal",
  "events": [
    "booking.created",
    "booking.cancelled",
    "booking.rescheduled"
  ],
  "active": true,
  "description": "Production webhook endpoint"
}

Available Events

booking.created - New booking created
booking.cancelled - Booking cancelled
booking.rescheduled - Booking time changed
booking.confirmed - Booking confirmed by host
event_type.created - New event type created
event_type.updated - Event type modified
event_type.deleted - Event type removed

Webhook Payload Example

{
  "id": "evt_abc123",
  "type": "booking.created",
  "created_at": "2025-01-28T10:00:00Z",
  "data": {
    "booking": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "event_type_id": "evt_456",
      "host_id": "usr_789",
      "guest_name": "Jane Smith",
      "guest_email": "jane@example.com",
      "starts_at": "2025-02-01T10:00:00Z",
      "ends_at": "2025-02-01T10:30:00Z",
      "status": "confirmed"
    }
  }
}

Webhook Security

All webhooks include an HMAC-SHA256 signature in the X-VardaCal-Signature header. Verify this signature to ensure the webhook is authentic:

def verify_webhook(payload, signature, secret)
  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
  ActiveSupport::SecurityUtils.secure_compare(expected, signature)
end