In this group we have all the API endpoints used to interact with webhooks. All calls to those endpoints require a valid ApiKey.
To start receiving webhooks calls you need to subscribe to a given event using the subscribe event and providing a target_url (must be unique). Once subscribed, whenever the event happens we will call the provided url with event related information
You can use the list endpoint at any time to see all the webhooks you have
To remove a webhook you need to use the unsubscribe endpoint passing the webhook id
Expected Responses
The target url should return a 200 OK as a result, if it returns any other response we will retry the delivery several times with some delay between them until a 200 OK is returned or we reach the maximum total amount of retries (currently 10).
As an exception of the rule, we are planning to implement an auto-removal of the webhook subscription when the response of the target_url is a 410 GONE, so if you're returning that as a response you may have your webhooks removed automatically in a future release
We also may remove webhooks that have been failing consistently for some time.
Verifying Responses
If you want to make sure the request you're receiving are in fact coming from Lodgify, you can verify the signature you'll find in the request header, under the ms-signature name. This signature has the format sha256=SIGNATURE.
Lodgify generates a unique secret key for each endpoint, this secret is only returned at the moment you create the webhook, so save it for verifying the signature later.
To verify the signature you need to:
1. Extract the signature from the header: the signature will be the part at the right after the = sign in the header named ms-signature
2. Prepare the payload: the payload is the actual JSON payload (i.e., the request body)
3. Determine the expected signature: Compute an HMAC with the SHA256 hash function. Use the webhook's signing secret as the key, and use the payload string as the message.
4. Compare the signatures: Compare the signature in the header to the expected signature. Please consider that the header will be Uppercase so depending on the method you use to calculate the signature you might need to convert to uppercase before comparing it