Webhook API

Webhook API v1

The Webhook API allows Integrating webhook with Enviso facilitates receiving real-time event notifications. When using the Webhook API, one can manage his own tenant, webhook, products, event, notification .

Terminologies

Here's a short description of what certain terminologies imply when using the Webhook API.

Tenant	A tenant is an organisation unit that registers on the Enviso application for selling their tickets through one or more sales channels (direct or indirect).
Webhook	A webhook is an HTTP-based callback function that allows lightweight, real-time, event-driven communication between Enviso and third-party integrators. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.
Event	An event is a categorisation for which webhook notifications can be managed (eg. order created, payment completed, etc.).
Notification	A notification is a callback for an event executed within the scope of a webhook.

Principles

The Webhook API is a REST API solution and attempts to conform to the RESTful design principles.

Important to know:

The API Key is required to be passed in HTTP Request Headers (x-api-key)
The request and response data is sent as JSON (HTTP Content-Type header = application/json)
All connections must be made over HTTPS, not HTTP.
All the query parameters are to be passed in lower case.
All date and time data in the API request/response are in the UTC-00:00 format. This means that the date and time in offer details, offer time slots, etc. are shown as per the UTC 00:00 date and time.
- yyyy-MM-ddTHH:mm:ssZ (Eg.: 1994-11-05T13:15:30Z)

Developers agreement

By using the Webhook API, you agree to our terms of service.

Request headers

The request and response data is sent as JSON.
```
content-type: application/json
```
The API Key is required to be passed in the HTTP Request Headers.
```
x-api-key: your_api_key
```
The Tenant Key is required to be passed in the HTTP Request Headers.
```
x-tenantsecretkey: your_tenant_key
```
The Authorization header is required for all endpoints.
```
authorization: Bearer SPACE your_jwt_token
```

Response status codes

The following HTTP status codes are used within the Webhook API.

Code	Description
200	OK The request was successful, resulting in everything working as expected.
201	Created The request was successful, resulting in the creation of new resource.
204	No Content The request was successfully processed, and is not returning any content.
400	Bad Request The server was unable to understand the request. The request is most likely malformed or a mandatory parameter is missing. Note It is recommended to make modifications to the current request and repeat the request.
401	Unauthorised The request has not been processed because it lacks valid authentication credentials for the target resource. If the request included valid authentication credentials, then the 401 response indicates that authorisation has been refused for the target resource.
403	Forbidden The server understood the request but refused to authorise it. Note This probably means you did not pass the API Key (x-api-key) in your request headers.
404	Not Found The requested resource does not exist. The resource may be available in the future. Subsequent requests by the client are permissible.
422	Unprocessable Entity The server understands the content type of the request entity, but was unable to process the contained instructions. For example, this error condition may occur if validation rules to process the entity fail.
429	Too Many Requests The server received too many requests in a given amount of time.
500	Internal Server Error The server encountered an unexpected error, which prevented it from fulfilling the request.
502	Bad Gateway The server has been unable to process the request at the moment.
503	Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Authentication

Contact Vintia support to obtain the Tenant key, API key and API secret key, which you need to start communicating to the API.

Once you have the needed information, you need to authenticate first before you'll be able to call the Scanning API.

For this, you'll need to use the Authentication API.

Going live

When going from the staging environment to the production environment:

Use the production environment API key and API secret key of the Authentication API.
Use the production environment API Key and Tenant key of the Booking API.
Note
Contact Vintia support to get your production environment keys of the Authentication API and Webhook API.
Change the base URL from the staging environment to the production environment.
- Production environment: https://api.enviso.io/webhookapi
- Staging environment: https://api.staging-enviso.io/webhookapi

Webhooks

Create webhook

Parameters

Parameter	Description
name	Name of the webhook indicating what this webhook is for.
description	A short description of what this webhook is for.
url	The integrator's URL where all the webhook notifications will be posted. The URL must be unique. It is NOT possible to create webhooks with the same URL. Warning Only HTTPS endpoints are allowed to ensure secure communication.
events	Subscription of Enviso events for which the notifications will be sent. See Available events. Note The same event can be subscribed to in multiple webhooks.
Webhook HMAC key	HMAC (Hash-based message authentication code) that will be used to generate signatures. Please securely save the generated HMAC key. Warning It is strongly advised to configure HMAC keys on your webhooks to enable signed notifications.

Available events

ORDER_CREATED - When an order is created.
ORDER_CONFIRMED - When an order is confirmed.
ORDER_CANCELLED - When an order is fully cancelled.
ORDER_REBOOKED - When an order is rebooked.
ORDER_PARTIALLY_CANCELLED - When some (not all) tickets of an order are cancelled.
PASS_SCANNED - When a pass (ticket or membership) is scanned.
ORDER_REBOOK_CANCELLED - When a rebook gets cancelled.
PAYMENT_LINK_CREATED - When a payment link is created.
BOOKING_CREATED - When a booking is created.
BOOKING_UPDATED - When a booking is updated.
BOOKINGS_CANCELLED - When a booking is cancelled.
VENUE_TASK_CREATED - When a task is created.
VENUE_TASK_UPDATED - When a task is updated.
VENUE_TASK_CANCELLED - When a task is cancelled.
VENUE_TASK_ASSIGNED - When a task is assigned.
VENUE_TASK_UNASSIGNED - When a task is unassigned.
DATA_CARRIER_CREATED - When a data carrier is created.
DATA_CARRIER_DELETED - When a data carrier is deleted.
DATA_CARRIER_STATUS_UPDATED - When a data carrier status is updated.
DATA_CARRIER_UPDATED - When a data carrier is updated.
EXECUTE_LOCK_ACTION - When a locker action is executed.
LOCKER_CREATED - When a locker is created.
LOCKER_DELETED - When a locker is deleted.
LOCKER_MODE_CHANGED - When the locker mode is changed.
LOCKER_STATE_CHANGED - When the locker state is changed.
LOCK_ALARM_CHANGED - When the alarm status of a lock has changed.
LOCKER_GROUP_CREATED - When a locker group is created.
LOCKER_GROUP_DELETED - When a locker group is deleted.
LOCKER_GROUP_UPDATED - When a locker group is updated.
LOCKER_USER_CREATED - When a locker user is created.
LOCKER_USER_DELETED - When a locker user is deleted.
LOCKER_USER_UPDATED - When a locker user is updated.
MAINTENANCE_DATA_CARRIER_CREATED - When a maintenance data carrier is created.
MAINTENANCE_DATA_CARRIER_DELETED - When a maintenance data carrier is deleted.
MAINTENANCE_DATA_CARRIER_STATUS_UPDATED - When a maintenance data carrier status is updated.
MAINTENANCE_DATA_CARRIER_UPDATED - When a maintenance data carrier is updated.
MASTER_CARD_SET_CREATED - When a Mastercard set is created.
MASTER_CARD_SET_DELETED - When a Mastercard set is deleted.
MASTER_CARD_SET_SYNCHRONIZED - When a Mastercard set is synchronized with a device.
MASTER_CARD_SET_UPDATED - When a Mastercard set is updated.

Response

Success response code: 201 Created

Request

var client = new RestClient("https://api.staging-enviso.io/webhookapi/v1/webhooks");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"name\":\"string\",\"description\":\"string\",\"url\":\"http://example.com\",\"events\":[\"string\"],\"hmacKey\":\"string\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/webhookapi/v1/webhooks")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"name\":\"string\",\"description\":\"string\",\"url\":\"http://example.com\",\"events\":[\"string\"],\"hmacKey\":\"string\"}")
  .asString();

Request

const data = JSON.stringify({
  "name": "string",
  "description": "string",
  "url": "http://example.com",
  "events": [
    "string"
  ],
  "hmacKey": "string"
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/webhookapi/v1/webhooks");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/webhookapi")

payload = "{\"name\":\"string\",\"description\":\"string\",\"url\":\"http://example.com\",\"events\":[\"string\"],\"hmacKey\":\"string\"}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("POST", "/v1/webhooks", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
  "id": "GUID"
 }

json

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Generate HMAC key

Response

Success response code: 200 OK

Request

var client = new RestClient("https://api.staging-enviso.io/webhookapi/v1/webhooks/generatehmac");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/webhookapi/v1/webhooks/generatehmac")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();

Request

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/webhookapi/v1/webhooks/generatehmac");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/webhookapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("GET", "/v1/webhooks/generatehmac", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
  "hmacKey": "string"
}

json

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Delete webhook

URL parameter

Name	Type	Required	Description
id	unique identifier	true	The ID of the webhook.

Response

Success response code: 204 No content

Request

var client = new RestClient("https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.delete("https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();

Request

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/webhookapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("DELETE", "/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Activate webhook

URL parameter

Name	Type	Required	Description
id	unique identifier	true	The ID of the webhook.

Response

Success response code: 204 No content

Request

var client = new RestClient("https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();

Request

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/webhookapi/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/webhookapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("POST", "/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Handle notifications

Each webhook notification contains the following fields:

id - The unique identifier of the webhook notification. It can be used to verify if it has been processed already.

tenant - The tenant key for which the notification was sent. It can be used in organisations that have multiple units to identify the unit.

event - The type of event to which the notification relates.

timestamp - The time the notification payload was created.

signature - The signature related to the notification. It should be used to verify that the payload was not modified in transit.

Apart from this, there is still the data field. The contents of this field depend on the event.

Here is an overview of the different events that can be enabled and their corresponding contents:

Sales events

ORDER_CREATED
```
"data" : {
    "id": "<Order id>"
}
```
ORDER_CONFIRMED
```
"data" : {
    "id": "<Order id>"
}
```

ORDER_CANCELLED

"data" : {
    "id": "<Order id>",
    "reason": "<Cancellation reason>" // Unknown - PaymentFailed - VenueCancelledFromSales - VenueCancelledFromApi - AutomaticCancellationExpiredOrderBySystem - PaymentRefunded - ResellerCancelledFromIndirectEndpoint - Visitor
}

ORDER_PARTIALLY_CANCELLED
```
"data" : {
    "id": "<Order id>"
}
```
ORDER_REBOOKED
```
"data" : {
    "id": "<Order id>"
}
```
ORDER_REBOOK_CANCELLED
```
"data" : {
    "id": "<Order id>"
}
```

PASS_SCANNED

"data" : {
    "id": "<Pass id>",
    "scannedDate": "<Pass scan date & time>",
}

PAYMENT_LINK_CREATED

"data" : {
    "paymentId": "<Payment id>",
    "paymentLink": "<Link to the payment form>",
    "amountValue": "<Value of the amount>",
    "amountCurrency": "<Currency of the amount>",
    "topicId": "<Topic id>",
    "topicType": "<Topic type>",
}

Booking events

BOOKING_CREATED
```
"data" : {
    "id": "<Booking id>"
}
```
BOOKING_UPDATED
```
"data" : {
    "id": "<Booking id>"
}
```

BOOKING_CANCELLED

"data" : {
    "ids": "[Booking1-id, Booking2-id]"
}

VENUE_TASK_CREATED
```
"data" : {
    "id": "<Task id>"
}
```
VENUE_TASK_UPDATED
```
"data" : {
    "id": "<Task id>"
}
```
VENUE_TASK_CANCELLED
```
"data" : {
    "id": "<Task id>"
}
```
VENUE_TASK_ASSIGNED
```
"data" : {
    "id": "<Task id>"
}
```
VENUE_TASK_UNASSIGNED
```
"data" : {
    "id": "<Task id>"
}
```

eLoxx events

LOCKER_STATE_CHANGED
```
"data" : {
    "lockId": "<Lock Id>"
}
```

DATA_CARRIER_CREATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

DATA_CARRIER_DELETED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

DATA_CARRIER_STATUS_UPDATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

DATA_CARRIER_UPDATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

EXECUTE_LOCK_ACTION

"data" : {
    "lockIds": "[Lock1-id, Lock2-id]"
}

LOCKER_CREATED
```
"data" : {
    "lockId": "<Lock Id>"
}
```
LOCKER_DELETED
```
"data" : {
    "lockId": "<Lock Id>"
}
```
LOCKER_MODE_CHANGED
```
"data" : {
    "lockId": "<Lock Id>"
}
```

LOCKER_GROUP_CREATED

"data" : {
    "lockerGroupId": "<Lockergroup Id>"
}

LOCKER_GROUP_DELETED

"data" : {
    "lockerGroupId": "<Lockergroup Id>"
}

LOCKER_GROUP_UPDATED

"data" : {
    "lockerGroupId": "<Lockergroup Id>"
}

LOCKER_USER_CREATED

"data" : {
    "lockerUserId": "<Locker User Id>"
}

LOCKER_USER_DELETED

"data" : {
    "lockerUserId": "<Locker User Id>"
}

LOCKER_USER_UPDATED

"data" : {
    "lockerUserId": "<Locker User Id>"
}

MAINTENANCE_DATA_CARRIER_CREATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

MAINTENANCE_DATA_CARRIER_DELETED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

MAINTENANCE_DATA_CARRIER_STATUS_UPDATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

MAINTENANCE_DATA_CARRIER_UPDATED

"data" : {
    "dataCarrierId": "<Data Carrier Id>",
    "lockerUserId": "<Locker User Id>"
}

MASTER_CARD_SET_CREATED

"data" : {
    "masterCardSetId": "<MasterCardSet Id>"
}

MASTER_CARD_SET_DELETED

"data" : {
    "masterCardSetId": "<MasterCardSet Id>"
}

MASTER_CARD_SET_SYNCHRONIZED

"data" : {
    "masterCardSetId": "<MasterCardSet Id>"
}

MASTER_CARD_SET_UPDATED

"data" : {
    "masterCardSetId": "<MasterCardSet Id>"
}

LOCK_ALARM_CHANGED
```
"data" : {
    "lockId": "<Lock Id>"
}
```

Warning

The maximum timeout for webhook notifications is 5 seconds. If we do not receive a response within 5 seconds, the notification is timed out and retried according to the retry mechanisms.

Note

Please note that the contents of the data fields may change. New properties may be added and should be treated as non-breaking changes.

It is advised to always be open to these changes to ensure proper handling of notifications.

{
  "id": "8172849c-e676-4c2a-8be8-2824cf41efa0",
  "tenant": "********",
  "event": "ORDER_CREATED",
  "timestamp": "2023-08-11T14:09:41.933Z",
  "data": {
    ...
  },
  "signature": "K0Z4V2lkM2pIaHpZdUNES3ZPRHJhcWNIaVFIN1R1SXpuZUgvSXBmMUtEQT0="
}