ETG API V3
Midoffice API
Webhooks
Receive booking changes’ webhook

Receive booking changes’ webhook

#midoffice

POST
ℹ️

Use this call if you:

  • Work as a Midoffice with an Agency or TMC.
  • Want to receive webhooks on orders as the Midoffice.

The call retrieves a webhook for the order statuses:

  • Creation.
  • Updating.
  • Cancellation.

Getting webhook scenario

  1. Provide the callback URL to the API support team.
  2. The API support team sets up the callback URL.
  3. Once the callback URL is set and the order operation is finished, the ETG API sends the webhook.
  4. Check if the webhook is received on your side and send the appropriate response.

Your server responses

The ETG listens to the following codes from your server and reacts accordingly:

  • Code 200 — the webhook is received successfully and doesn’t need a retry.
  • Code 500 — the ETG needs to retry sending for 7.5 minutes with the intervals:
    • 30 seconds.
    • 60 seconds.
    • 90 seconds.
    • 120 seconds.
    • 150 seconds.
    • 300 seconds.
    • One hour.
    • Every 12 hours for 7 days. In total, 14 attempts.

Payload

agreement_number String optional
The Midoffice agreement number.
partner_order_id String required

The unique partner booking ID.

ℹ️
  • The minimum length is 1 character.
  • The maximum length is 256 characters.
type String required

The event type that caused the callback.

ℹ️

The possible values:

  • updated.
  • cancelled.
  • created.

The payload example:

{
  "type": "updated",
  "agreement_number": "B2B-12345/1",
  "partner_order_id": "0b370500-5321-4046-92c5-5982f1a64fc6"
}

Secure data

signature String required
The hexadecimal digits generated by the HMAC algorithm.
timestamp Int required

The date and time of creating a webhook token in the Unix Timestamp format.

ℹ️
  • The minimum date is January 1, 1970.
  • You can find it in the token signature when decoding.
token String required
The randomly generated string with the length of 50 characters.

The secure data example:

{
  "signature": {
    "signature": "7865d225dbee1b54909er153d193e0b57b707ebe81ff5b2e1b71ebaf749bec23",
    "timestamp": 1574146939,
    "token": "d3395025-1ee7-49a2-bd86-e4bd6b9908b2"
  }
}

Whole fields example 

{
  "data": {
    "type": "updated",
    "agreement_number": "B2B-12345/1",
    "partner_order_id": "0b370500-5321-4046-92c5-5982f1a64fc6"
  },
  "signature": {
    "signature": "7865d225dbee1b54909er153d193e0b57b707ebe81ff5b2e1b71ebaf749bec23",
    "timestamp": 1574146939,
    "token": "d3395025-1ee7-49a2-bd86-e4bd6b9908b2"
  }
}

Signature verification

To verify the webhook issued by the ETG:

  1. Concatenate the timestamp and token values. The “token” means the one sent by the ETG in the webhook data.
  2. Encode the resulting string with the HMAC algorithm:
    1. Use your API Key token as a key.
    2. Use the SHA256 digest mode.
  3. Use the hexdigest() method to make a resulting string.
  4. Compare the resulting string to the signature.
  5. Optional. Cache the token locally and don’t honor any subsequent request with the same token. This will prevent replay attacks.
  6. Optional. Check that the timestamp is within the token lifetime.

Examples

Python 

import hashlib, hmac
def verify(api_key, token, timestamp, signature):
    hmac_digest = hmac.new(key=api_key,
                           msg='{}{}'.format(timestamp, token),
                           digestmod=hashlib.sha256).hexdigest()
    return hmac.compare_digest(unicode(signature), unicode(hmac_digest))

Ruby 

require 'openssl'
def verify(api_key, token, timestamp, signature)
  digest = OpenSSL::Digest::SHA256.new
  data = [timestamp, token].join
  signature == OpenSSL::HMAC.hexdigest(digest, api_key, data)
end

PHP 

function verify($apiKey, $token, $timestamp, $signature)
{
  // check if the timestamp is fresh
  if (abs(time() - $timestamp) > 15) {
    return false;
  }
  // returns true if signature is valid
  return hash_hmac('sha256', $timestamp . $token, $apiKey) === $signature;
}

Node.js 

const crypto = require('crypto')
const verify = ({ apiKey, timestamp, token, signature }) => {
   const encodedToken = crypto
           .createHmac('sha256', apiKey)
           .update(timestamp.toString().concat(token))
           .digest('hex')
   return (encodedToken === signature)
}