Webhooks

VaultRE also offers "webhooks" for interested third parties. You can register a URL with VaultRE and that URL will receive a JSON payload notification when a certain event occurs within VaultRE. For example, you can receive a notification when a new contact is added, or when a property is updated.

When an event occurs in VaultRE, your URL endpoint will be called with a HTTP POST request containing a JSON body (Content-Type: application/json) - for example:

{
  "event": "user.update",
  "data": {
    "id": 911
  },
  "accountid": 603,
  "timestamp": "2023-05-17T06:42:19+00:00",
  "itemBodies": [
    {
      "dataModel": "User",
      "data": "{\"showOnWeb\": true, \"firstName\": \"Matt\", \"adminAccess\": true, \"username\": \"redacted\", \"websiteUrl\": \"\", \"staffTypeId\": 1, \"photo\": {\"thumb_360\": \"https://s3-ap-southeast-2.amazonaws.com/staffphotos-clientvault-com/603/small.8989234298-911-image.jpg\", \"original\": \"https://s3-ap-southeast-2.amazonaws.com/staffphotos-clientvault-com/603/8989234298-911-image.jpg\"}, \"permissions\": {\"globalPropertiesRead\": true, \"deleteProperties\": false, \"accessPropertyFinancials\": true, \"canLogin\": true, \"globalNotesRead\": false, \"accessAlarmDetails\": true, \"globalContactsReadWrite\": true, \"accessSales\": true, \"settings\": true, \"sendSMS\": true, \"globalNotesReadWrite\": true, \"globalPropertiesReadWrite\": true, \"accessPropertyManagement\": true, \"globalActionListsReadWrite\": true, \"partialEditProperty\": false, \"modifyWebsiteContent\": false, \"deleteContacts\": true, \"globalTasksReadWrite\": true}, \"role\": \"residentialSales\", \"lastName\": \"Healy\", \"email\": \"test@test.com.au\", \"position\": \"Director\", \"lastLogin\": \"2023-05-17T06:41:11+00:00\", \"phoneNumbers\": [{\"number\": \"0400000000\", \"typeCode\": \"M\", \"type\": \"Mobile\", \"comment\": null}], \"paAccess\": [], \"id\": 911, \"profile\": null}"
    }
  ]
}

The webhook payload includes the data of the object being referenced. In same cases, there may be multiple items in the itemBodies array (for example, when a property is updated and that property is both for sale and for rent).

All webhook requests come with a HTTP header containing a signature. You should verify the signature to assert that the request has come from VaultRE. The requests include a header X-VaultRE-Signature which is similar to a Stripe webhook signature.

The header will contain:

t=<timestamp in milliseconds>,sha512=<hmac_sha512 hash>

The hash payload consists of the current timestamp in milliseconds (as a string), the . character, and the JSON body concatenated. The payload is SHA512 hashed and HMAC signed with your API key as the secret. This allows you to verify the webhook call came from us and the timestamp allows you to avoid replay attacks by rejecting calls where the timestamp is outside your threshold.

It is important to note that the hash payload is strictly the above, without parsing, filtering, or adjustments; any modification to the JSON body will cause the match to fail - e.g. removing whitespace between variables in the following example causes the resulting hash to not match:

1704070800000.{"event": "property.update", "data": {"id": 1234567890}, "accountid": 1234, "timestamp": "2024-01-01T00:00:00+00:00"}

versus

1704070800000.{"event":"property.update","data":{"id":1234567890},"accountid":1234,"timestamp":"2024-01-01T00:00:00+00:00"}

Please note that webhook requests are not sent with any other form of authentication or authorisation, so your receiving endpoint will need to accept requests without requiring other authorisation checks.

Contact api@vaultre.com.au for more information.