TBD

Limitations

• Webhooks are only available for applications with grant type client_credentials using an access of type "Agency Manager" (single agency access) and scope "api.profilesondemand.read".
• Notifications can not be tailored to include / exclude specific profiles. Notifications will be sent for all profiles within a travel agency.
• Notifications might be delivered, even if no actual profile data has been changed.
  • The notification itself denotes a profile identifier and nothing more. Specifically, it does not contain any profile data or information on what may have changed within the profile.

Receiving Webhooks

TBD

Payload

{
  "eventTime": "18.03.2024T09:56:17Z"
  "profileType": "TRAVELLER",
  "event": "UPDATE",
  "uuid": "25b46ba4-0e9e-4baa-83bd-ac21a50ef998",
  "company": {
    "uuid": "34f277f5-2618-4c9e-aa08-affa9f02dfaa"
  }
}

Message authentication

Each Webhook invocation will include the custom header "X-FacesWebhookSignature", which consist of the request body hashed using HMAC-SHA256 with the secret configured during Webhook setup in hex format.

Example: Using the above payload and secret S3cret! one would compute a hash value of bd5c6ea7cbf75262ec0f835213f213b345dd9645624945622555475592def94f

Delivery

Payloads are delivered via HTTPS POST only. Each notification will be transmitted with an individual POST request without applying any batching logic.

The recipient Server must present a trusted certificate and return a HTTP 2XX status code within 10 seconds for the notification delivery to be considered successful.

In case of an error Umbrella Faces will attempt to re-deliver the the notification up to 5 times before silently discarding the notification.

Managing Webhooks

Webhooks are managed in a self-service fashion via the following set of APIs.

Search / List Webhooks 

Allows searching through a paged list of active Webhook subscriptions for the calling application.

Parameters

curl -v -H "Authorization: Bearer <token>" \
    "https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/webhooks?q=&page=0&pageSize=10"

{
    "moreResults": false,
    "results": [
        {
            "uuid": "56b19ace-1fa9-4346-a97c-f621c5138342",
            "name": "My Example Webhook",
            "profileTypes": [
                "TRAVELLER",
                "CORPORATE"
            ],
            "eventTypes": [
                "CREATE",
                "UPDATE",
                "DELETE"
            ],
            "url": "https://my.example.com/webhook/notify"
        }
    ]
} 

Create new Webhook

Register a new Webhook subscription

curl TBD

{
    "uuid": "c7c769bc-9310-4b29-b27c-f34355ec66b4",
    "name": "Notify myIntegrationX",
    "profileTypes": [
        "TRAVELLER",
        "CORPORATE"
    ],
    "eventTypes": [
        "CREATE",
        "UPDATE",
        "DELETE"
    ],
    "url": "https://my.example.com/webhook/notify",
    "secret": {
        "sensitiveValuePresent": true
    }
}

Update existing Webhook

Modify Webhook subscription

Parameters

curl TBD

{
    "uuid": "c7c769bc-9310-4b29-b27c-f34355ec66b4",
    "name": "Notify myIntegrationX",
    "profileTypes": [
        "TRAVELLER",
        "CORPORATE"
    ],
    "eventTypes": [
        "CREATE",
        "DELETE"
    ],
    "url": "https://my.example.com/webhook/notify",
    "secret": {
        "sensitiveValuePresent": true
    }
}

Delete Webhook

Remove Webhook subscription

Parameters

curl -v -X DELETE \
    -H "Authorization: Bearer <token>" \
    https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/webhook/c7c769bc-9310-4b29-b27c-f34355ec66b4