Partner booking integration guide - kaddio/documentation GitHub Wiki

This guide explains how external booking platforms integrate with Kaddio to receive booking notifications via webhooks.

Overview

When users book through your platform with Kaddio care providers, Kaddio sends webhook notifications when bookings are confirmed.

Important: Webhooks are only sent for bookings by logged-out users with a booking reference.

Setup

1. Contact Kaddio to register as a partner and provide your webhook endpoint URL
2. Implement a webhook endpoint that accepts POST requests
3. Use correct booking reference format when creating bookings

Booking Reference Format

Recommended format: {partner_id}_{your_reference} Example: yourcompany_ABC123

Your partner ID is assigned by Kaddio during setup. The prefix determines which webhook endpoint receives notifications. References without a valid prefix use a fallback configuration.

Webhook Specification

Endpoint Requirements:

• HTTPS (required for production)
• Accept POST with JSON payload
• Respond with HTTP 200 OK

Request:

POST https://api.yourcompany.com/webhooks/kaddio
Content-Type: application/json

{
  "SourceSystem": "Kaddio",
  "CareProvider": "https://example.kaddio.com",
  "AdditionalInfo": "yourcompany_ABC123",
  "ExternalBookingId": "kaddio_booking_id_xyz"
}

Fields:

• SourceSystem: Always "Kaddio"
• CareProvider: Care provider's Kaddio URL
• AdditionalInfo: Your booking reference (with prefix)
• ExternalBookingId: Kaddio's internal booking ID

Integration Example

1. Generate prefixed reference:

const bookingReference = `yourcompany_${internalBookingId}`;
// Result: "yourcompany_ABC123"

2. Redirect user to Kaddio:

https://example.kaddio.com/booking?reference=yourcompany_ABC123

3. Receive webhook when booking confirms:

app.post('/webhooks/kaddio-bookings', (req, res) => {
  const { AdditionalInfo, ExternalBookingId } = req.body;
  
  // Extract internal reference (handle both prefixed and non-prefixed)
  const parts = AdditionalInfo.split('_');
  const internalId = parts.length > 1 ? parts[1] : AdditionalInfo;
  
  updateBookingStatus(internalId, {
    status: 'confirmed',
    kaddioBookingId: ExternalBookingId
  });
  
  res.status(200).json({ received: true });
});

Note: Bookings complete successfully even if webhooks fail. Implement monitoring on your side.

Security

Custom Headers: You can configure authentication headers during partner setup:

{
  "url": "https://api.yourcompany.com/webhooks/kaddio",
  "headers": {
    "X-API-Key": "your-secret-key"
  }
}

Requirements:

• Production endpoints must use HTTPS with valid SSL

Support

Contact Kaddio's integration team with:

• Partner ID request
• Webhook endpoint URL
• Custom header requirements
• Expected booking volume