How to Use Webhooks

Leverage Propexo’s webhooks to get updates that you care about.

Overview

Many of our customers use webhooks to get updates on events like lease status changes, new leads, and more. We offer webhook events for new and changed data for all of our data models, job statuses and more.

Why use webhooks?

Webhooks are a way to integrate with Propexo so you know about changes to your data in real-time. Instead of polling the API for changes, you can register a webhook and we’ll send you a notification when something changes. You can subscribe to changes on a per-data model basis, so you are only notified when the data you care about changes.

How do webhooks work?

You set up a URL on your system that we will send a POST request to when something changes. We will send you a JSON payload with the data that changed. You can then use that data to update your system.

1
const express = require('express');
2
const app = express();
3
4
app.post('/webhook/leases', async (req, res) => {
5
    const lease = req.body;
6
7
    // Perform business logic
8
    const { status: prevStatus } = lease?.diff?.previous;
9
    const { status } = lease?.diff?.new;
10
    if (prevStatus === 'pending' && status === 'approved') {
11
        const { email } = lease?.tenant;
12
        // Send an email to the tenant
13
        await app.sendEmail(email, 'Your lease has been approved');
14
    }
15
16
    res.send(200);
17
});

Then, in Propexo, you can register your webhook URL and subscribe to the events you care about (“Data Update” on the leases model in this example).

Now each time Propexo identifies a change in the leases model for a particular lease in your integration, you will be notified via a POST request to your webhook URL.

Below is an example of how Propexo might send a webhook request to your system. Note, this is a simplified payload for the example and is not intended to represent a complete webhook payload.

$
POST <your_path>
>
Host: <your_domain>
>
Content-Type: application/json
>
propexo-signature: <payload_signature>
>
>
{
>
    "meta": {
>
        "object": "leases",
>
        "integration_id": "cuid_1234567890",
>
    },
>
    "record_id": "cuid_1234567890",
>
    "diff": {
>
        "previous": { "status": "pending" },
>
        "new": { "status": "approved" }
>
    }
>
}

Important Note for the DATA_NEW event

When you subscribe to a DATA_NEW webhook event, it is automatically disabled until your integration has finished its first full data sync. This is to prevent you from receiving a flood of events when you first set up your integration. After the first full sync, the DATA_NEW event will be enabled and you will receive a webhook event for every new record that is created in the model to which you are subscribed.

Sequencing

Oftentimes Propexo needs to fully hydrate data over more than one request to a Property Management System. For example, several integrations provide a minimal set of data for residents, applicants, or leads. The minimal dataset might only include an ID and name. We then need to make a subsequent request to retrieve additional information like phone and email. In these cases, you should fully test to ensure that you are receiving all of the data you need with the subscribed webhook event. Some customers only need to subscribe to the DATA_NEW event, others may want to subscribe to the DATA_UPDATE event as well.

Optionally, many customers use webhooks as a notification system and then query the associated API endpoint to retrieve a full data record. For example, you may subscribe to the DATA_UPDATE event for the leases model. When you receive a webhook event, you can then query the /leases/:id endpoint to retrieve the full lease record.

Signed Payloads

Propexo signs every webhook payload. This signature is sent in the propexo-signature header. You can use this signature to verify that the webhook was sent by Propexo and not a malicious third party.

The secret that is used to sign the payload is available in your integration settings. You can find it by going to the “Webhooks” page in the Propexo dashboard and clicking on the “Settings” button.

Here is an example of how you might verify the signature in Node.js:

1
import { timingSafeEqual, createHmac } from 'crypto'
2
3
const createHmacSignature = ({ data, secret }): string => {
4
  return createHmac('sha256', secret).update(data).digest('hex')
5
}
6
7
const compareSignatures = ({ suppliedSignature, data }): Boolean => {
8
  const generatedSignature = createHmacSignature({ data, secret })
9
  const source = Buffer.from(suppliedSignature)
10
  const comparison = Buffer.from(generatedSignature)
11
  return timingSafeEqual(source, comparison)
12
}
13
14
return compareSignatures({ suppliedSignature: req.headers['propexo-signature'], data: req.body })