Webhook

Webhooks allow RentalCover to push booking events to your server in real time, so you don't need to poll Notifications/list. When a booking is created, updated, or cancelled, RentalCover sends an HTTP POST to a URL you configure.

Setup

1. Expose an HTTPS endpoint on your server that accepts HTTP POST requests.
2. Contact your Cover Genius CSE with your endpoint URL and the events you want to subscribe to. Your CSE configures the webhook in the RentalCover backend.
3. Verify HMAC signatures on all incoming requests (see HMAC Verification below).
4. Return an HTTP 2xx status code to acknowledge each event.

Available events

Event	Description
booking.created	A new booking has been confirmed.
booking.updated	A booking has been modified (dates, cover, or customer details changed).
booking.cancelled	A booking has been cancelled.

Acknowledging events

Your endpoint must return HTTP 2xx to confirm receipt. If your server returns a non-2xx response, RentalCover considers delivery failed. Contact your CSE for retry behaviour details.

HMAC verification

Each webhook request includes an HMAC-SHA256 signature in the X-Signature header. Verify this signature before processing the payload. It confirms the request originated from RentalCover and was not altered in transit.

curl --location '[your_server_endpoint]'
--header 'Content-Type: application/json'
--header 'X-Signature: [shared_secret]'
--data-raw '[request_payload]'

Reject requests with an invalid signature without acknowledging them.

Your HMAC secret key is provided when your webhook is configured by your CSE.

<?php

// Shared HMAC key provided by your CSE at webhook configuration
$secret = 'your_hmac_secret_key';

// Read the raw request body
$requestBody = file_get_contents('php://input');

// Read the HMAC signature from the request header
$receivedHMAC = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Calculate the expected signature
$calculatedHMAC = hash_hmac('sha256', $requestBody, $secret);

// Compare using a timing-safe function to prevent timing attacks
if (hash_equals($calculatedHMAC, $receivedHMAC)) {
    $data = json_decode($requestBody, true);
    // ... handle $data ...
    http_response_code(200);
    echo 'Webhook verified and processed';
} else {
    http_response_code(400);
    echo 'Invalid signature';
}

Cancellation event

Payload

{
  "Event": "BOOKING_CANCELLED",
  "Bookings": [
    {
      "BookingId": "12345",
      "Reference": "AB12-345C-INS",
      "Type": "FullProtection",
      "Code": "FULLPROTECTION11",
      "SupplierReference": "CXCSUK8F7C0U",
      "MetaData": "{\"provider_id\":\"PARTNER123\"}"
    }
  ],
  "Status": "Cancelled",
  "Currency": "USD",
  "TotalAmount": 60,
  "TotalAmountFormatted": "US$60.00",
  "PartnerReference": "PARTNER-REF-001",
  "PartnerCollectingPayment": false,
  "FromDate": "2025-08-01 00:00:00",
  "ToDate": "2025-08-08 00:00:00",
  "CancelledOn": "2025-07-15 10:20:25",
  "Source": "Frontend",
  "CancelReason": "Trip has been cancelled"
}

Fields

Field	Type	Description
Event	string	Event type identifier. Example: BOOKING_CANCELLED.
Bookings	array	Array of affected bookings. Contains multiple entries for bundled bookings.
Bookings[].BookingId	string	Internal booking ID.
Bookings[].Reference	string	Booking reference (ends in -INS). Use this for all claims and support.
Bookings[].Type	string	Policy type.
Bookings[].Code	string	Policy code.
Bookings[].SupplierReference	string	Insurer's policy reference.
Bookings[].MetaData	string	JSON string of the MetaData passed in the original quote or purchase request.
Status	string	Booking status at the time of the event.
Currency	string	Three-letter ISO 4217 currency code.
TotalAmount	float	Original total protection amount.
TotalAmountFormatted	string	Formatted total amount.
PartnerReference	string	Your booking reference, if provided.
PartnerCollectingPayment	boolean	Whether the partner was collecting payment.
FromDate	datetime	Protection start date.
ToDate	datetime	Protection end date.
CancelledOn	datetime	Date and time the booking was cancelled.
Source	string	Where the cancellation originated: Frontend, Backend, or API.
CancelReason	string	Reason provided for the cancellation.