Notifications system

Most of the API methods that update our systems do so asynchronously. This allows us to offer better reliability to callers of the API and also allows us to offer better performance.

You can register to be notified of the results of these asynchronous operations by using the Notifications System. There are two methods that we use to send notifications to you:

  1. We’ll send you a message over HTTP. You have the option of choosing JSON or XML as the format of these messages.
  2. We’ll send you HTML emails describing the notification.

You can also choose to mix and match which notification method is used depending on the Topic of the notification. For example, you might want to be notified by HTTP+JSON about bookings that have been successfully created, but have a member of staff be notified by email when they submit an invalid booking to our API.

HTTP Notification Messages

We’ll POST XML or JSON with details of the notification to a URL on your website that you specify. Note that this URL has to be a secured by a SSL certificate.

We’ll also include an HTTP header X-EC-NotificationKey with the notification key that we issued you when setting up your account. You should check that this has the expected value and you must reject any HTTP calls that don’t specify the correct notification key using an HTTP 403 Forbidden code.

If your web service returns any code other than 200 OK in response to our notification then we’ll assume that you failed to process the notification. We’ll keep retrying to submit failed notifications for two days until we receive a 200 OK code. If two days elapse before we receive a 200 OK code then we’ll give up and email the notification message to your support email address.

Example Invalid booking notification

POST /your-url HTTP/1.1
Host: www.yoursite.com
Content-Type: application/json; charset=utf-8
Accept: application/json
X-EC-NotificationKey: secret-notification-key
Content-Length: 205

{
  "Topic": "Booking:Invalid",
  "AgentBookingId": "X8347848",
  "ValidationMessages": [
    {
      "Message": "02-10-2015 isn't a valid start date to 'General English' in 'Brighton'"
    }
  ]
}

Email Notification Messages

Email notification messages are a useful way to receive notifications without having to write code. For example, if you setup email notifications for the Booking:Invalid topic, we’ll email details of an invalid booking to the member of staff that submitted the booking.

If we’re unable to deliver the email to the member of staff, for example if their mailbox is full, then we’ll forward the email as an attachment to your support email address.