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 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
|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|
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