Skip to main content

Webhooks

What is a webhook?

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.

Host Building can publish webhooks to external systems when certain events occur. These contains information about the event and the triggering user.

When subscribing, you will receive all hooks for the requested category. E.g. If you require tenant hooks, you will receive the events for tenant_created, tenant_enabled...

Request signing​

We sign each webhook call with a signature in the request header. This will allow any third party to verify that a request was sent by Host.

When a webhook is created for a client we auto-generate a secret key for each endpoint and we use that secret key to sign the request. The signature is added into the header of that request under the 'Host-Signature' attribute.

See Webhook Signing for more information.

Configuring webhooks​

We don't currently offer self-service configuration for webhooks.

Getting setup

Contact Host Building with your endpoint and the events you want to subscribe to. You will be provided with a signature secret to use when verifying the source of the webhook.

Structure​

All webhooks follow a common structure. All dates are UTC timezone, ISO-8601 formatted.

{
  "event": "event_booked",
  "event_at": "2022-05-03 18:12:13",
  "source": "au.host-building.com",
  "data": {
    "properties": "string"
  }
}

Available hooks​

Event booked

Triggered when a user books an event.

{
    "event": "event_booked",
    "event_at": "2022-05-03 18:12:13",
    "source": "au.host-building.com",
    "data": {
      "id": 1233,
      "event_id": 52,
      "event_name": "Example event",
      "event_image": "https://cdn.au.host-building.com/data/image.png",
      "user": {
          "id": 1123123,
          "name": "Test user",
          "email": "test@cbre.com",
      },
      "session_start": "2022-09-12 18:00:00", // UTC
      "session_end": "2022-09-12 19:00:00",  // UTC
      "cost": "$20.00"
    }
  }