> For the complete documentation index, see [llms.txt](https://partner-docs.covergenius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://partner-docs.covergenius.com/rentalcover/webhook.md).

# Webhook

Webhooks allow RentalCover to push booking events to your server in real time, so you don't need to poll [Notifications/list](/rentalcover/endpoints/notifications-list.md). 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](#hmac-verification) below).
4. Return an HTTP 2xx status code to acknowledge each event.

## Available events

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="229.633544921875">Event</th><th>Description</th></tr></thead><tbody><tr><td><code>booking.created</code></td><td>A new booking has been confirmed.</td></tr><tr><td><code>booking.updated</code></td><td>A booking has been modified (dates, cover, or customer details changed).</td></tr><tr><td><code>booking.cancelled</code></td><td>A booking has been cancelled.</td></tr></tbody></table>

## 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.

{% code overflow="wrap" %}

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

{% endcode %}

{% hint style="info" %}
Reject requests with an invalid signature without acknowledging them.
{% endhint %}

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

```php
<?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&#x20;

### Payload

```json
{
  "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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://partner-docs.covergenius.com/rentalcover/webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.