Webhooks

Get notifications sent to you when availability or booking changes

To use this capability add ventrata/webhooks to your Octo-Capabilities header.

This capability allows you to create webhooks which will notify a given URL whenever an action happens in Ventrata, e.g. Booking Update, Booking Cancellation, or Availability Change.

Create Webhook

POST https://api.ventrata.com/octo/webhooks

Create a new webhook

Request Body

Name	Type	Description
url	string	The URL to call when the webhook is triggered
event	string	The event that will trigger the webhook

200

{
  "event": "booking_update",
  "url": "https://example.com/webhooks/availability_update"
}

Field	Description
url	A fully formed URL. If you want to include basic authentication credentials that is supported also. For example: https://user:[e-mail]/webook https://example.com/webhook
event	The event that will trigger the webhook. Possible values are: booking_update triggered when an existing booking is confirmed, updated or cancelled. availability_update triggered when an availability changes.
retryOnError	Whether the webhook should be retried if the HTTP endpoint doesn't return a success status (200 to 299), default is true.
useContactLanguage	Whether the webhook event should attempt to use the language configured by the guest when they booked. This makes sure the data in the webhook body is in the guest's language, default is true.
headers	A object of headers to be used on each webhook request. This can be useful to keep your endpoint secure.
capabilities	A list of capabilities that will be activated before triggering the webhook which will affect the data included in the webhook body.

An example response will look like this:

{
  "id": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "event": "booking_update",
  "url": "https://example.com/webhooks/availability_update",
  "retryOnError": true,
  "useContactLanguage": true,
  "headers": {},
  "capabilities": [ "octo/pricing" ]
}

We recommend for testing you can use ngrok to create an endpoint which connects to your localhost. You can then make test bookings with the same credentials and see the webhook requests arrive.

Note that you don't set the capabilities in the request body when creating the webhook, you should just include them in the Octo-Capabilities header when calling the POST /webhooks endpoint.

When an event is triggered the webhook will perform a POST HTTP request to the specified URL, the request body will look like this depending on the event type:

booking_update

{
  "webhook": {
    "id": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
    "event": "booking_update",
    "url": "https://example.com/webhooks/booking_update",
    "retryOnError": true,
    "useContactLanguage": true,
    "headers": {},
    "capabilities": [ "octo/pricing" ]
  },
  "booking": {
    "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "testMode": true,
    "resellerReference": null,
    "supplierReference": "X749G9",
    "status": "ON_HOLD",
    "utcExpiresAt": "2020-06-07T17:06:37Z",
    "utcConfirmedAt": null,
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "cancellable": true,
    "cancellation": null,
    "freesale": false,
    "notes": "optional notes on the booking",
    "availability": {
      "id": "2020-07-01T14:30:00-05:00",
      "localDateTimeStart": "2020-07-01T14:30:00-05:00",
      "localDateTimeEnd": "2020-07-02T02:30:00-05:00",
      "allDay": true,
      "openingHours": []
    },
    "contact": {
      "fullName": null,
      "emailAddress": null,
      "phoneNumber": null,
      "locales": [],
      "country": null
    },
    "deliveryMethods": [
      "VOUCHER",
      "TICKET"
    ],
    "voucher": {
      "redemptionMethod": "DIGITAL",
      "utcRedeemedAt": null,
      "deliveryOptions": []
    },
    "unitItems": [
      {
        "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
        "resellerReference": null,
        "supplierReference": "408H44",
        "unitId": "child",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      },
      {
        "uuid": "ec1e2622-1359-437b-83f8-15182759d605",
        "resellerReference": null,
        "supplierReference": "BSDYM4",
        "unitId": "adult",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      },
      {
        "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
        "resellerReference": null,
        "supplierReference": "E5K92G",
        "unitId": "adult",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      }
    ]
  }
}

availability_update

{
  "webhook": {
    "id": "d7876d4c-34c0-4d90-8569-9da49268fa29",
    "event": "availability_update",
    "url": "https://example.com/webhooks/availability_update",
    "retryOnError": true,
    "useContactLanguage": true,
    "headers": {},
    "capabilities": [ "octo/pricing" ]
  },
  "availability": {
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 12,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
}

This endpoint will return a list of all existing webhooks.

List Webhooks

GET https://api.ventrata.com/octo/webhooks

List all webhooks

Path Parameters

Name	Type	Description
	string

200

[
  {
    "id": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
    "event": "booking_update",
    "url": "https://example.com/webhooks/availability_update",
    "retryOnError": true,
    "useContactLanguage": true,
    "headers": {},
    "capabilities": [ "octo/pricing" ]
  },
  {
    "id": "d7876d4c-34c0-4d90-8569-9da49268fa29",
    "event": "availability_update",
    "url": "https://example.com/webhooks/availability_update",
    "retryOnError": true,
    "useContactLanguage": true,
    "headers": {},
    "capabilities": [ "octo/pricing" ]
  }
]

Delete Webhooks

DELETE https://api.ventrata.com/octo/webhooks/:id

Delete an existing webhook

Path Parameters

Name	Type	Description
:id	string	The webhook id

200