Use webhooks to get real-time updates

Do you want to be proactively informed of your customer activities? You're at the right place! 💪

This is the documentation for version 2 of our webhooks. Looking for the version 1? Look there.

Webhook principles

A webhook sends an HTTP request to your application's URL in response to an activity in Koala's API. For example, you can configure a webhook to receive requests when a customer creates a contract, or when a contract is claimed.

Subscribing to our webhook can help you with:

• Claim management: If you handle claim management, our webhook will keep you informed of the current status of the claim.
• Customer service: You can feed your CRM so that your customer service is aware of everything happening with your customers.
• Customer experience: You can contact disrupted travellers to offer them special assistance or care.

Claims notifications are sent as soon as we have determined internally the status of the claims (usually, expect to receive it a few hours after the event has occurred, at the latest 48 hours).

Create a webhook endpoint

To start using Koala webhooks, you must set up an HTTP endpoint on your application that can accept unauthenticated webhook request with a POST method. The URL path of the endpoint can be anything, for example /koala_webhooks.

The expected request body is described in the Swagger and the request will contain the following headers:

{
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Koala-Signature": "<generated_signature>",
  "Webhook-Version": "v2"
}

The purpose of Koala-Signature header is explained in the section below.

Secure your webhook endpoint

The Koala-Signature header is there to verify that the request truly comes from Koala.

This is achieved by comparing the value of Koala-Signature against a hash of the request body.

This hash is created using the algorithm SHA256 with the secret you provided us, and is encoded into hexadecimal.

Here is an example implementation of how to verify the signature using JavaScript:

const crypto = require('crypto');

function verifySignature(request, secret) {
  const hmac = crypto.createHmac('sha256', secret);

  // The hash will use the *raw* body of the request
  hmac.update(request.body, 'utf8');

  // Creates the hash using the hexadecimal encoding
  const digest = hmac.digest('hex');

  return digest === request.headers['Koala-Signature'];
}

Subscribe to Koala webhooks

Once the webhook endpoint is set up on your side, you will need to provide us with:

• A URL on which we can POST the events
• A secret key used to secure the webhook

You can optionally choose which events you receive. Events are listed in the Swagger.

Error handling

If you fail to process the webhook request (downtime due to scheduled maintenance, network error, schema validation error, etc.), we will retry the request during 7 days after it failed.

Our system will consider the webhook request failed if the response code is different from 200 or if the request times out after 5 seconds.

Example webhook requests

Here is an example webhook request body for a claim event:

{
  "data": {
    "claim": {
      "claimedAt": "2023-06-23T10:09:04.546Z",
      "compensation": {
        "amount": 80,
        "currency": "EUR"
      },
      "contract": {
        "coveredEvent": {
          "journeys": [
            {
              "flights": {
                "arrivalAirport": {
                  "city": "New York",
                  "iata": "JFK",
                  "name": "John F. Kennedy International Airport"
                },
                "arrivalDate": "2023-07-30T08:35:00.000Z",
                "departureAirport": {
                  "city": "Paris",
                  "iata": "CDG",
                  "name": "Charles de Gaulle Airport"
                },
                "departureDate": "2023-07-30T07:10:00.000Z",
                "number": "AF8223"
              },
              "segments": []
            }
          ],
          "stays": []
        },
        "createdAt": "2023-06-23T10:08:40.861Z",
        "id": "395c0b75-456a-4c34-b85e-f2d796241643",
        "priceDetails": {
          "coveredEventPrice": 100,
          "currency": "EUR",
          "retailPremiumTaxesIncluded": 15
        },
        "product": {
          "name": "Flex",
          "type": "WITHDRAWAL"
        },
        "subscription": {
          "id": "c779e8da-4f53-4b58-95bc-a6702588fee8",
          "bookingNumber": "6TG9896HTM",
          "customer": {
            "email": "john.doe@gmail.com",
            "firstName": "John",
            "lastName": "Doe"
          }
        },
        "travelers": [
          {
            "ageRange": "ADULT",
            "countryOfResidence": {
              "id": "FR",
              "name": "France"
            }
          }
        ]
      },
      "reason": {
        "type": "CANCELATION"
      },
      "status": "REFUNDED"
    }
  },
  "event": "claim.updated"
}

The claim was triggered when the customer canceled his booking with number 6TG9896HTM, making him eligible for an 80€ compensation.

In this example, if the secret you provided us with was my_secret then the value of the Koala-Signature header would be 98bdc70d97aa5b6ae3e90254e3ac81e0c2dbd9b2f2ac780d5ab2a2d52758f480.

Here is another example webhook request body for an event triggered by the creation of a contract:

{
  "data": {
    "contract": {
      "coveredEvent": {
        "journeys": [
          {
            "flights": [
              {
                "arrivalAirport": {
                  "city": "New York",
                  "iata": "JFK",
                  "name": "John F. Kennedy International Airport"
                },
                "arrivalDate": "2023-07-30T08:35:00.000Z",
                "departureAirport": {
                  "city": "Paris",
                  "iata": "CDG",
                  "name": "Charles de Gaulle Airport"
                },
                "departureDate": "2023-07-30T07:10:00.000Z",
                "number": "AF8223"
              }
            ],
            "segments": []
          }
        ],
        "stays": []
      },
      "createdAt": "2023-06-23T10:08:40.861Z",
      "id": "395c0b75-456a-4c34-b85e-f2d796241643",
      "maximumExpectedCompensation": {
        "amount": 80.5,
        "currency": "EUR"
      },
      "priceDetails": {
        "coveredEventPrice": 100,
        "currency": "EUR",
        "retailPremiumTaxesIncluded": 15
      },
      "product": {
        "name": "Flex",
        "type": "WITHDRAWAL"
      },
      "subscription": {
        "id": "c779e8da-4f53-4b58-95bc-a6702588fee8",
        "bookingNumber": "6TG9896HTM",
        "customer": {
          "email": "john.doe@gmail.com",
          "firstName": "John",
          "lastName": "Doe"
        }
      },
      "travelers": [
        {
          "ageRange": "ADULT",
          "countryOfResidence": {
            "id": "FR",
            "name": "France"
          }
        }
      ]
    }
  },
  "event": "contract.created"
}