API Webhooks Implementation

Introduction

Webhooks is a simple HTTP requests that are being sent out when a given event occurred. You can define a single or separate handlers (URLs) for each event and when this event handlers received a webhooks requests, it will return a http 200 response accordingly.
If you're not familiar with webhooks concept, there is a very good read on sendgrid blog.


Webhooks Payload Detail

  • Webhooks are sent as POST HTTP/1.1 requests with JSON payload
  • Payload vary depending on the event, but will always contains type, timestamp, links, signature & shortSignature
  • Webhooks expect 200 OK HTTP response as a confirmation, meaning the event has been acknowledged by your application.

Webhooks Acknowledgement

  • Webhooks handler from your server is expected to return HTTP response 200 OK as event acknowledgement
  • When webhooks receive a http 200 response from your webhooks handler, it is marked as acknowledged and will not be sent again
  • In case our webhooks get any other HTTP response or no response at all after waiting for more than 20 second, webhooks delivery is marked as failed and there will be retry
  • Number of retries
    • Total number of retries is 10 times
    • 1st retry will take place 1 minute after original webhook
    • 2nd retry will take place 2 minutes after the 1st retry
    • Intervals between subsequent retries will be 1, 2, 4, 8, 16, 32, 64 minutes on the same day
    • After the 7th retry, subsequent retries will be every 24 hours for the next 3 days

Webhooks Events

Name
Description
booking_status_changed Fired whenever your booking's status changes. Payload consists of booking's complete current data
booking_files_ready Fired when vouchers for an approved booking is ready to be downloaded. Payload will contain booking's complete current data
product_added Fired when a new Product is available. links.self will contain API endpoint URL to request for product details
product_updated Fired when Product's data (description, pricing, attributes etc) changes. links.self will contain API endpoint URL to request for product details.
product_removed Fired when Product is unpublished/offline

Webhooks Security

In order to ensure the origin of the webhook call, we recommend using payload signing.
In the Agents Marketplace webhooks configuration page, you can (re)generate your hash secret key, which will be used to create HMAC for the webhook call.
Signature is a sha256 HMAC of the payload in JSON format with your hash secret key.
Example checking of Signature in PHP:


$json = json_decode($request->getBody(), true);
$signature = $json['signature'];
$payload = $json;
unset($payload['signature']);
$signature === hash_hmac('sha256', json_encode($payload), 'MY_WEBHOOK_SECRET_KEY');

Shortsignature is a simplified version of signature. It is based on values of 3 fields. "type", "timestamp" and "UUID" concatenated using |.
Example checking of Short Signature in PHP:


$json = json_decode($request->getBody(), true);
$short_signature = $json['shortSignature'];
$payload = $json;
$signature === hash_hmac('sha256', $payload['type'].'|'.$payload['timestamp'].'|'.$payload['item']['uuid'], 'MY_WEBHOOK_SECRET_KEY');


Steps in Configuring Webhooks

  • Create a webhook event handler in your server
  • The main task for this webhook handler is to receive the payload from our Webhooks server, save it as a job in your server queue and then return a http 200 response. You must ensure it is able to return a response within 20 second
  • Create a job in your server to loop through the server queue and process each of the job accordingly
  • Login to Agents MarketPlace
  • Click on API and then Webhooks 2 tab
  • Generate a webhook hash secret key by clicking on the "Generate" button
  • Input a valid URL's of your event handler in each of the webhooks event
  • Update the webhooks event handler in your server to use this new secret key
  • Start testing your webhooks event handler