Webhooks (Proposed Draft)

This capability is not part of the official OCTO specification. This is a draft / unofficial capability, proposed by Peek Pro and Ventrata, provided as an example only.

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

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

Create Webhook

POST {host}/webhooks

Create a new webhook

Request Body

{
  "id": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "event": "booking_update",
  "url": "https://example.com/webhooks/availability_update"
}

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:

{
  "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": "unit_child321",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      },
      {
        "uuid": "ec1e2622-1359-437b-83f8-15182759d605",
        "resellerReference": null,
        "supplierReference": "BSDYM4",
        "unitId": "unit_adult123",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      },
      {
        "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
        "resellerReference": null,
        "supplierReference": "E5K92G",
        "unitId": "unit_adult123",
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "utcRedeemedAt": null,
          "deliveryOptions": []
        }
      }
    ]
  }
}

This endpoint will return a list of all existing webhooks.

List Webhooks

GET {host}/webhooks

List all webhooks

Path Parameters

[
  {
    "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 {host}/webhooks/:id

Delete an existing webhook

Path Parameters

Last updated