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 requirements and safety as early as possible than a last-minute surprise.
Example webhook registration confirmation
{
"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.pathcan not be used to derive the updated restriction attribute.
Updated 11 months ago