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

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 and without any guaranteed order.

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 -v -X POST \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    --data '{
    "name": "Notify myIntegrationX",
    "profileTypes": [
        "TRAVELLER",
        "CORPORATE"
    ],
    "eventTypes": [
        "CREATE",
        "UPDATE",
        "DELETE"
    ],
    "url": "https://my.example.com/webhook/notify",
    "secret": {
        "value": "MyNewSecret"
    }
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/webhook

{
    "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 -v -X PATCH \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    --data '{
    "name": "Notify myIntegrationX",
    "profileTypes": [
        "TRAVELLER",
        "CORPORATE"
    ],
    "eventTypes": [
        "CREATE",
        "UPDATE",
        "DELETE"
    ],
    "url": "https://my.example.com/webhook/notify",
    "secret": {
        "value": "MyNewSecret"
    }
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/webhook/c7c769bc-9310-4b29-b27c-f34355ec66b4

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