Webhooks

Stay up to date with Sherpa°

Sherpa° Webhooks

A webhook is a user-defined callback over HTTP. You can use webhooks to notify your app or web application when certain events occur in sherpa° related to travel restrictions and requirements.
For example, you might want to alert your remote application when a country opens its border for travel, when a new quarantine policy is imposed or when there is a change in the visa requirements. Your remote application doesn't have to periodically poll our sherpa° services (via the REST APIs) to determine whether changes have occurred.

🚧

Early Access

This feature is in early access. Read about our product maturity levels here.

Operations with a webhook via the sherpa° API

Registering a webhook

To register a new webhook in sherpa° you have to provide following information:

  • A name for the webhook ( for example, "Updates for the United States")
  • The url where the callback should be sent if an event happens
  • secret is a user-defined string to be used as the key to generate the sha256 HMAC hex digest value in the X-Sherpa-Signature header e.g. X-Sherpa-Signature: sha1=2d28cdd681337b008b3c702edd92eea23792c2f9
  • The events is a list of events to be registered e.g. ["restriction_created"], on which the callbacks should be triggered.
  • frequency is the frequency at which a webhook response payload is expected eg. "daily" (every day at 8:00 am EST). frequency is "instant" by default
  • includeReferenceOnly is a flag to indicate if the referenced data should be included in the webhook response payload
  • active is a flag to indicate whether the webhook is enabled or not.

<SHERPA_API_URL>/webhooks

{
  "data": {
    "type": "WEBHOOK",
    "attributes": {
      "name": "All restrictions",
      "url": "http://my-domain/travel-restrictions/hook",
      "secret": "A sacred secret, so sea crit, no one knows it!",
      "events": ["restriction_all"],
      "includeReferenceOnly": false,
      "frequency": "instant",
      "active": true
    }
  }
}

Unregistering a webhook

To unregister or delete a webhook, execute a DELETE request to the following URL:

<SHERPA_API_URL>/webhooks/{webhookId}

curl -X DELETE 
-H "affiliateId: sherpa-partner-id" 
-H "Content-Type: application/json"
 <SHERPA_API_URL>/webhooks/101?key=aBcd1EfGh234iJkLM56

Query webhooks

  • To get all your registered webhooks, execute a GET request to the following URL:

<SHERPA_API_URL>/webhooks

curl -X GET 
-H "affiliateId: sherpa-partner-id"
-H "Content-Type: application/json"
 <SHERPA_API_URL>/webhooks?key=aBcd1EfGh234iJkLM56
  • To get a specific registered webhook, execute a GET request to the following URL:

<SHERPA_API_URL>/webhooks/{webhookId}

curl -X GET 
-H "affiliateId: sherpa-partner-id"
-H "Content-Type: application/json"
 <SHERPA_API_URL>/webhooks/103?key=aBcd1EfGh234iJkLM56

Update an existing webhook

To update a webhook, execute a PATCH request to the following URL:

<SHERPA_API_URL>/webhooks/{webhookId}

{
  "data": {
    "type": "WEBHOOK",
    "id": "0016a4e0-2d11-491e-b043-f58b0622a4f0",
    "attributes": {
      "name": "All new restrictions created",
      "events": ["restriction_created"]
    }
  }
}

Events

Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on sherpa°'s travel requirement and restriction database, which your server's payload URL intercepts and acts upon.
When configuring a webhook, you can choose which events will send you payloads. Only subscribing to the specific events can limit the number of HTTP requests to your server.

Each event may correspond to a certain set of actions or information that are relevant to your travel in terms of a restriction, procedure or requirement. For example, if you subscribe to the restrictions_all event for the United States, you'll receive detailed payloads every time a new restriction or procedure is added, updated and deleted for the United States.

Event Type

Description

Status

travel_restriction_all

A new restriction and procedure is created, updated and deleted

In Effect

restriction_all / procedure_all

A new restriction/procedure is created, updated and deleted

In Effect

restriction_created / procedure_created

A new restriction/procedure is created

In Effect

restriction_updated / procedure_updated

A new restriction/procedure is updated

In Effect

restriction_deleted / procedure_deleted

A new restriction/procedure is deleted

In Effect

restriction:category_added / restriction:subCategory_added / procedure:category_added / procedure:subCategory_added

A new restriction/procedure that belongs to a given category and/or subcategory is added

In The Future.

restriction:category_removed / restriction:subCategory_removed / procedure:category_removed / procedure:subCategory_removed

A new restriction/procedure that belongs to a given category and/or subcategory is removed

In The Future.

country_all

A country is added or removed

In The Future.

country_added

A country is added

In The Future.

country_removed

A country is removed

In The Future.

region_all

A region is added or removed

In The Future.

region_added

A region is added

In The Future.

region_removed

A region is removed

In The Future.

country:digest

A summary of all the restrictions, procedures and requirements of a country or countries

In The Future.

region:digest

A summary of all the restrictions, procedures and requirements of a region or regions

In The Future.

restriction:digest

A summary of all the restrictions.

In The Future.

procedure:digest

A summary of all the procedures.

In The Future.

Delivery Headers

HTTP POST payloads that are delivered to the configured webhook URL will contain several request headers

Header

Example

Description

Content-Type

application/json

X-Sherpa-Signature

This is the HMAC hex digest of the body, and is generated using the SHA-256 hash function and the secret as the HMAC key.

User-Agent

Sherpa-Webhooks/1.0

Event Payloads

Webhook payload object common properties

Each webhook event payload has a common structure of properties. Certain property values can be unique to the type of event. You can find the common properties of the payload object below.

Key

Type

Description

meta

object

Payload may contain some meta information about the webhook.

data

object

Payload contain an array of data related to events.

included

object

Payload includes the actual data which caused to trigger the event. Data would be included only if the webhook is registered with includeReferenceOnly as false

Meta
Meta in the payload may contain any information such as copyright and version about the webhook.

Data
All data elements have a common object structure.

Key

Type

Description

id

string

Webhook id

type

string

Type of the data element. In this case it will always be 'WEBHOOK'

attributes

object

attributes contain the information related to the webhook event

relationships

object

relationships include the data reference to restrictions, procedures, countries, and /or regions

Attributes
attributes contain the webhook event-related information such as eventType, createdAt, resourceType etc..

Relationships
relationships have the same object structure as that of the relationships in sherpa° travel restriction & safety API response

Included
included has the same object structure as that of the included in sherpa° travel restriction & safety API response

revision
Events with updated eventTypes *_UPDATED have an additional attribute called revision that includes a list of changes made to that particular entity.

revision[0].kind can be of following types:
A - Array was modified
E - Item was edited
D - Item was deleted
N - Item is new
revision[0].lhs - refers to the "left hand side" and the old value
revision[0].rhs - refers to the "right hand side" and the new value
revision[0].path - refers to the full attribute path of the attribute that was changed

Use Cases

# Get notified when new restrictions are added
For every traveller, it is really important to know beforehand about the new restriction that may affect their travel to their destination.

Example webhook.

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": {
    "type": "WEBHOOK",
    "id": "0016a4e0-2d11-491e-b043-f58b0622a4f0",
    "attributes": {
      "name": "All new restrictions created",
      "url": "http://my-domain/travel-restrictions/hook",
      "events": ["restriction_created"],
      "includeReferenceOnly": true,
      "frequency": "instant",
      "active": true
    }
  }
}

Example payload send to your registered callback url

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": [
    {
      "id": "c412c06c-99c0-4ccc-c6c7-7c99c23903c6",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "RESTRICTION_CREATED",
        "createdAt": "2020-10-15T09:33:00Z",
        "country": "USA",
        "resourceType": "RESTRICTION",
        "category": "RESTRICTED_ENTRY",
        "subCategory": "ENTRY"
      },
      "relationships": {
        "restrictions": {
          "meta": {
            "count": 1
          },
          "data": [
            {
              "id": "5524bfd9-9ed8-4aea-a152-6945aacd126d",
              "type": "RESTRICTION"
            }
          ]
        }
      }
    },
    {
      "id": "c412c06c-99c0-4ccc-c6c7-7c99c23903c6",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "RESTRICTION_CREATED",
        "createdAt": "2020-10-15T09:36:00Z",
        "country": "CAN",
        "resourceType": "RESTRICTION",
        "category": "NO_ENTRY",
        "subCategory": "ENTRY"
      },
      "relationships": {
        "restrictions": {
          "meta": {
            "count": 1
          },
          "data": [
            {
              "id": "728f8d91-ab34-4366-8ad9-ccbb7c15ad36",
              "type": "RESTRICTION"
            }
          ]
        }
      }
    },
    {
      "id": "c412c06c-99c0-4ccc-c6c7-7c99c23903c6",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "RESTRICTION_CREATED",
        "createdAt": "2020-10-15T09:58:00Z",
        "country": "AUS",
        "resourceType": "RESTRICTION",
        "category": "NO_RESTRICTION",
        "subCategory": "ENTRY"
      },
      "relationships": {
        "restrictions": {
          "meta": {
            "count": 1
          },
          "data": [
            {
              "id": "fcdfec99-e46a-4daa-ba9d-8724d38dd734",
              "type": "RESTRICTION"
            }
          ]
        }
      }
    }
  ],
  "included": []
}

# Get notified about all changes to procedures
A change can happen anytime, which may open a new possibility to travel or may lead to some adjustments in your travel plans. It is always better to get to know about the changes in the travel restrictions and safety as early as possible than a last-minute surprise.

Example webhook registration.

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": {
    "type": "WEBHOOK",
    "id": "0016a4e0-2d11-491e-b043-f58b0622a4f1",
    "attributes": {
      "name": "All changes in travel procedures",
      "url": "http://my-domain/travel-procedures/hook",
      "events": ["procedure_all"],
      "frequency": "instant",
      "includeReferenceOnly": false,
      "active": true
    }
  }
}

Example payload send to your registered callback url

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": [
    {
      "id": "b412b06b-99b0-4bbc-b6b7-7b99b23903b1",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "PROCEDURE_UPDATED",
        "createdAt": "2020-11-09T14:33:00Z",
        "country": "CAN",
        "resourceType": "PROCEDURE",
        "category": "DOC_REQUIRED",
        "subCategory": "ON_ARRIVAL",
        "revision": [
          {
            "kind": "N",
            "path": "included.origin.countries",
            "rhs": ["GBR", "FRA"]
          }
        ]
      },
      "relationships": {
        "procedures": {
          "meta": {
            "count": 1
          },
          "data": {
            "id": "5524bfd9-9ed8-4aea-a152-6945aacd126d",
            "type": "PROCEDURE"
          }
        }
      }
    },
    {
      "id": "b412b06b-99b0-4bbc-b6b7-7b99b23903b2",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "PROCEDURE_CREATED",
        "createdAt": "2020-11-09T14:36:00Z",
        "country": "AUS",
        "resourceType": "PROCEDURE",
        "category": "COVID_19_TEST",
        "subCategory": "BEFORE_ARRIVAL"
      },
      "relationships": {
        "procedures": {
          "meta": {
            "count": 1
          },
          "data": {
            "id": "728f8d91-ab34-4366-8ad9-ccbb7c15ad36",
            "type": "PROCEDURE"
          }
        }
      }
    },
    {
      "id": "b412b06b-99b0-4bbc-b6b7-7b99b23903b3",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "PROCEDURE_DELETED",
        "createdAt": "2020-11-09T14:48:00Z",
        "country": "AUS",
        "resourceType": "PROCEDURE",
        "category": "QUARANTINE",
        "subCategory": "ON_ARRIVAL"
      },
      "relationships": {
        "procedures": {
          "meta": {
            "count": 1
          },
          "data": {
            "id": "fcdfec99-e46a-4daa-ba9d-8724d38dd734",
            "type": "PROCEDURE"
          }
        }
      }
    }
  ],
  "included": [{...}]
}

# Get notified when we start tracking a new region for their travel measures
It is possible to know at the earliest when we add a new region to our service to track the travel restriction and safety measures.

Example webhook registration.

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": {
    "type": "WEBHOOK",
    "id": "0016a4e0-2d11-491e-b043-f58b0622a4f1",
    "attributes": {
      "name": "A new region is added",
      "url": "http://my-domain/travel-restrictions/hook",
      "events": ["region_added"],
      "frequency": "instant",
      "includeReferenceOnly": false,
      "active": true
    }
  }
}

Example payload send to your registered callback url

{
  "meta": {
    "copyright": "Sherpa",
    "version": "2.5.0"
  },
  "data": [
    {
      "id": "a412b06a-99b0-4aaa-a6a7-7a99a23903a6",
      "type": "WEBHOOK_CALLBACK",
      "attributes": {
        "eventType": "REGION_ADDED",
        "createdAt": "2020-11-27T17:03:00Z",
        "resourceType": "REGION"
      },
      "relationships": {
        "regions": {
          "meta": {
            "count": 1
          },
          "data": {
            "id": "US-NY",
            "type": "REGION"
          }
        }
      }
    }
  ],
  "included": [{...}]
}

Known issues

  • revision.path can not be used to derive the updated restriction attribute.

Did this page help you?