Versions Compared

Old Version 10

changes.mady.by.user Remo Räber

Saved on

compared with

New Version Current

changes.mady.by.user Susanne Schlegel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Webhook notifications will not be sent to the application triggering the profile change. Only other applications with webhook subscriptions will be notified

Receiving Webhooks

TBD

Payload

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

UTC-Timestamp in format "dd.MM.yyyy'T'HH:mm:ss'Z'" of when the event has originally happened

profileType

The profile type for which this notification is sent:

  • TRAVELLER
  • CORPORATE
event

The notification type:

  • CREATE
  • UPDATE
  • DELETE
  • PING
    (for connectivity checks only, profileType will be set to TRAVELLER and uuid to a random UUID)
uuidThe Umbrella Faces UUID of the affected profile

company

.uuid

For profileType TRAVELLER only: UUID + Name of the company currently associated with the traveler profile.

 

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 bd5c6ea7cbf75262ec0f835213f213b345dd9645624945622555475592def94fof 92649059fe0fc9457cba7b4e80da4fa42ce0528583517da66826c61e75dba624

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 over the next 2 hours before silently discarding the notification.

Note

Depending on the number of notifications on our Webhook notification queue, individual notifications might be delayed for a longer time

Managing Webhooks

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

Note

Each create / update triggers an immediate "PING" notification (with no retries) to the configured endpoint, and will only be accepted if the PING is succesful

Search / List Webhooks 

Endpointapi/v1/configuration/webhooks
Request methodGET

...

Code Block
languagejs
titleExample response
collapsetrue
{
    "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

Note

Each create triggers an immediate "PING" notification (with no retries) to the configured endpoint, and will only be accepted if the PING is succesful

Endpointapi/v1/configuration/webhook
Request methodPOST

...

Code Block
languagebash
titleExample request
curl TBD
Code Block
languagejs
titleExample response
collapsetrue
{
    "uuid": "c7c769bc-9310-4b29-b27c-f34355ec66b4",
    -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": {
        "sensitiveValuePresentvalue": true"MyNewSecret"
    }
}

 

Update existing Webhook

...

' https://hurricane.umbrellanet.ch/uf-test/api/v1/configuration/webhook

...

...
Modify Webhook subscription
Parameters
...
Name
...
Description
...
Validation
...
 Code Block
 Code Block
languagebash
titleExample request
curl TBD
languagejs
titleExample response
collapsetrue
{
    "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
To update a Webhook, please delete and re-create it
Delete Webhook
Endpointapi/v1/configuration/webhook/<uuid>
Request methodDELETE
Remove Webhook subscription.
Note: After deleting a Webook, some notifications that were already placed on the notification queue before deletion may still be delivered
Parameters
Name
Description
Validation
<uuid>The UUID of the subscription to be deletedRequired parameter
...