Configuring and receiving webhooks

During onboarding you have the ability to provide us with a URL that we can send webhooks to.
We will always send POST requests to this URL and expect a 200 response status code.

Payload fields

When you receive a webhook from us, you can safely assume that each payload contains at least the following fields:

idULID (string)A unique ordered ID assigned to the payload of the webhook.01GTKD6ZYFVQMR0RWP4HBBHNZC
dataobject OR array of objectsPaylod here will be exactly the same as in the relevant endpoint
actionstringThe action that informs you the cause of this webhookchannel.activated
complete list
createdUTC Zulu ISO8601 StringWhen the payload was initially created2023-03-03T09:35:24Z
versionstringVersion of the webhook1.


If your webhook handler does not respond with a 200 OK we will retry it up to 5 times or until successful response, with exponential back-off: 1 sec, 5 sec, 10 sec, 1 hr, 6 hr

IP range

Our webhooks will be sent from the following IP range You are advised to whitelist only this IP for your webhook handler for better security.


We will include a Signature header in each webhook call. You can use this field to verify that Hospitable is the sender.

To do this you need the following:

  • Payload
  • Webhook secret (given to you during onboarding)

We sign the webhook using the standard HMAC with the SHA256 function.

For example:

  • Payload is {"foo": "bar"}
  • Your webhook secret is "123456"
  • The signature header cc99bf5947391ddb0d0d9866f5b9d3a68e8b273c5ac8f699b4ae2399a7433118

You can now apply the HMAC to verify

function verify(string $payload, string $signature): bool
  $expected = hash_hmac('sha256', $payload, env('SECRET', '123456'));
  return hash_equals($expected, $signature);