Be informed of claims status

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

Webhook principles

We have designed webhooks to which you can subscribe to receive notifications of your customers' claims.

You will receive notifications from us as soon as we have determined internally the status of the claims (usually, expect to receive a notification within a few hours after the event has occurred, at the latest 48 hours). By subscribing to our webhook, you will get the same information we do at the same time!

When do I need to interface with Koala's webhook?

Subscribing to our webhook can help you with:

• Claim management: If you handle claim management, our webhook will keep you informed of the eligibility of the claim.
• Customer service: You can feed your CRM with claim details 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.

How does it work?

To subscribe to our webhook, you will need to send us:

• A URL on which we can POST information
• A secret of your choice.

Once received, Koala will configure your webhook and notify your URL via HTTP POST with all the details of the claim. Your role will be to interpret the notification received and use it for your claim management.

You will receive a notification per contract when a contract becomes eligible for compensation and/or when we receive the bank details for the payment.🤓

If you are interested in receiving non-eligible claims or any extra information, please let us know! :::

Subscribing to the claim webhook: Headers

The webhook will contain the following set of request headers:

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

Koala-Signature is a hash generated on the fly using your client secret and the request body itself, we use

it to certify the authenticity of the request. This means each request will have a different Koala-Signature hash.

Subscribing to the claim webhook: Body

You must configure your webhook to accept the following type of body:

{
  "claimedAt": DateTime,
  "compensation"?: {
    "amount": number,
    "currency": string (3-letters code),
  } | undefined,
  "contract": {
    "coveredEvent": Flight | Journey | Trip,
    "createdAt": DateTime,
    "subscription": {
      "bookingNumber": string
    }
  },
  "reason"?: {
    "type": string ('CANCELATION' | 'FLIGHT_CANCELED' | 'FLIGHT_DELAYED' | 'FLIGHT_DIVERTED' | 'MISSED_CONNECTION'),
  } | undefined,
  "status": string ("ACCEPTED" | "REFUNDABLE" | "REFUNDED" | "AUTOMATICALLY_REJECTED" | "REJECTED" | "MANUAL_VERIFICATION_NEEDED"),
}

For all possible claim statuses, please check our OpenAPI doc on claim creation response.

Here are the different coveredEvent types:

Flight {
  "arrivalAirport": {
    "city": string,
    "iata": string (3-letters code),
    "name": string,
  },
  "arrivalDate": DateTime,
  "departureAirport": {
    "city": string,
    "iata": string (3-letters code),
    "name": string,
  },
  "departureDate": DateTime,
  "number": string (airline code + flight number),
}

Journey {
  "flights": Flight[],
}

Stay {
  "address": {
    "country": {
      "id": string (2-letters code),
      "name": string,
    },
    "line1"?: string | undefined,
    "line2"?: string | udefined,
    "line3"?: string | undefined,
    "line4"?: string | undefined,
    "locality"?: string | undefined,
    "postcode"?: string | undefined,
    "region"?: string | undefined,
  },
  "endDate": DateTime,
  "name": string,
  "startDate": DateTime,
}

Trip {
  "journeys": Journey[] | [],
  "stays": Stay[] | [],
}

Verifying Koala's request

To certify that the notification truly comes from Koala, you will need to compare the Koala-Signature header against a hash of the request body with the secret you gave us.

To do so, you can run the following:

const crypto = require('crypto');

function verifySignature(request, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(request.body), 'utf8');
  const digest = hmac.digest('hex');
  return digest === request.headers['Koala-Signature'];
}

What happens if the webhook request fails?

Sometimes, your server hosting your webhook will fail to receive the claim due to various reasons (downtime due to scheduled maintenance, network error, schema validation error, etc...).

For these cases we have implemented a retry system. If your webhook times out or does not reply with a successful HTTP code (2xx), we will retry sending the claim. The worker will try sending the claim again during some hours. But don't worry, we will not spam your webhook! Our system will space out requests increasingly.

Example of notification

Please find below an example of notification for a delayed flight between Paris and New York:

{
  "claimedAt": "2022-02-07T11:31:27.000Z",
  "compensation": {
    "amount": 100,
    "currency": "EUR"
  },
  "contract": {
    "coveredEvent": {
      "arrivalAirport": {
        "city": "New York",
        "iata": "JFK",
        "name": "John F. Kennedy International Airport"
      },
      "arrivalDate": "2021-07-30T08:35:00.000Z",
      "departureAirport": {
        "city": "Paris",
        "iata": "CDG",
        "name": "Charles de Gaulle Airport"
      },
      "departureDate": "2021-07-30T07:10:00.000Z",
      "number": "AF8223"
    },
    "createdAt": "2021-12-05T18:42:55.000Z",
    "subscription": {
      "bookingNumber": "6TG9896HTM"
    }
  },
  "reason": {
    "type": "FLIGHT_DELAYED"
  },
  "status": "ACCEPTED"
}

Here you can see that booking 6TG9896HTM has had a delayed flight allowing it to be eligible for 100 EUR.

If the secret you gave us is "my_secret", we will hash the payload above with it, and the Koala-Signature header will be:

4d03d41bf8cbbb3382896f9336d3c109e652774baf638b23b0aecf5d895ef9d1

For GDPR reasons, we are not sharing any information about the customer details. You will need to use the field

bookingNumber to associate the claim to the right booking. 🐨 :::