Web Hooks

Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL to receive data about changes to data on the API.

Subscribing

To subscribe to the webhooks just hit this endpoint giving it the url of your endpoint that is set up to receive notifications.

http://<APIROOT>/webhook/subscribe/?url=<URL_OF_YOUR_ENDPOINT>

We are using Amazon SNS to send out the notifications, more documentation can be found here - Amazon SNS docs

Once you hit the subscribe endpoint, it will be sent a SubscriptionConfirmation message as below. You will need to hit the SubscribeURL to confirm your subscription.

POST / HTTP/1.1
x-amz-sns-message-type: SubscriptionConfirmation
x-amz-sns-message-id: 165545c9-2a5c-472c-8df2-7ff2be2b3b1b
x-amz-sns-topic-arn: arn:aws:sns:us-east-1:123456789012:MyTopic
x-amz-sns-subscription-arn: arn:aws:sns:us-east-1:123456789012:MyTopic:2bcfbf39-05c3-41de-beaa-fcfcc21c8f55
Content-Length: 1336
Content-Type: text/plain; charset=UTF-8
Host: example.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent

{
  "Type" : "SubscriptionConfirmation",
  "MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
  "Token" : "2336412f37fb687f5d51e6e241d09c805a5a57b30d712f794cc5f6a988666d92768dd60a747ba6f3beb71854e285d6ad02428b09ceece29417f1f02d609c582afbacc99c583a916b9981dd2728f4ae6fdb82efd087cc3b7849e05798d2d2785c03b0879594eeac82c01f235d0e717736",
  "TopicArn" : "arn:aws:sns:us-east-1:123456789012:MyTopic",
  "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:MyTopic&Token=2336412f37fb687f5d51e6e241d09c805a5a57b30d712f794cc5f6a988666d92768dd60a747ba6f3beb71854e285d6ad02428b09ceece29417f1f02d609c582afbacc99c583a916b9981dd2728f4ae6fdb82efd087cc3b7849e05798d2d2785c03b0879594eeac82c01f235d0e717736",
  "Timestamp" : "2012-04-26T20:45:04.751Z",
  "SignatureVersion" : "1",
  "Signature" : "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
  "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"
  }

A typical request script would be:

<?php

$snsFullMessage = detectRequestBody();
if ($snsFullMessage && isset($snsFullMessage['SubscribeURL'])) {
    echo file_get_contents($snsFullMessage['SubscribeURL']);
    die();
} else {
    // Connect to the api
    \tabs\api\client\ApiClient::factory(
       "http://{$brandCode}.api.carltonsoftware.co.uk",
        APIKEY,
        APISECRET
    );

    // This condition can be changed to the relevant update name (documented in the next section)
    if ($snsFullMessage->updatename == 'PropertyUpdate') {
        list($propref, $brandcode) = explode($snsFullMessage->Message->updatedid);

        // Now that you have the propref / brandcode
        // You can query the api and update any local data
        // you have stored
    }
}

/**
 * Return the post body
 * 
 * @return string
 */
function detectRequestBody() {
        $data = json_decode(file_get_contents('php://input'), true);
        if (JSON_ERROR_NONE !== json_last_error() || !is_array($data)) {
            throw new \RuntimeException('Invalid POST data.');
        }

	return $data;
}

Notification Message

Once you have confirmed your subscription you will start to receive notifications of each change to data within the API. The notification json you receive will have a Message member, the value of this will be a json object in the following format.

{
    "id": 2,
    "updatename": "PropertyUpdate",
    "updatetime": {
        "date": "2013-12-15 07:14:40",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "updatedid": "1105_NO",
    "updateadditionaldata": "",
    "processid": "0.38745900 1387092819"
}

• id - A unique id from the change log on the api.
• updatename - A reference to the type of data that has changed. List below.
• updatetime - Time that the data was updated.
• updatedid - The id of the object that was updated.
• updateadditionaldata - Additional information is given for some updates e.g. image filename on a ImageUpdate.
• processid - An id assigned to the batch of updates.

Update names

• AreaDelete (updatedid = areacode)
• AreaInsert (updatedid = areacode)
• AreaUpdate (updatedid = areacode)
• ImageDelete (updatedid = propref & updateadditionaldata = image filename)
• ImageInsert (updatedid = propref & updateadditionaldata = image filename)
• ImageUpdate (updatedid = propref & updateadditionaldata = image filename)
• LocationDelete (updatedid = locationcode)
• LocationInsert (updatedid = locationcode)
• LocationUpdate (updatedid = locationcode)
• PriceInsert (updatedid = propref)
• PriceUpdate (updatedid = propref)
• PropertyDelete (updatedid = propref)
• PropertyInsert (updatedid = propref)
• PropertyUpdate (updatedid = propref) This includes updates to availability.
• SourcecodeDelete (updatedid = sourcecode)
• SourcecodeInsert (updatedid = sourcecode)
• SourcecodeUpdate (updatedid = sourcecode)
• SpecialPriceDelete (updatedid = propref)
• SpecialPriceInsert (updatedid = propref)
• SpecialPriceUpdate (updatedid = propref)

Securing Webhooks

Keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private, our best suggestion is to simply include a secret key in the URL your provide and check that GET parameter in your scripts.