Webhooks

Overview: How to Use Propexo Webhooks

Webhooks let you receive automatic updates when data changes in your Propexo integrations — without needing to repeatedly poll the Propexo API.

With webhooks, you can subscribe to specific event types and, in some cases, narrow that down to specific data models so you only receive relevant updates.

How Webhooks Work

  1. Set up a public endpoint on your system to receive POST requests from Propexo.
  2. Register your webhook URL in the Propexo dashboard. [LINK HERE]
  3. Select the events you want to subscribe to (and models, where applicable).
  4. Propexo sends a POST request to your URL whenever a subscribed event occurs.
  5. The request contains a JSON payload describing the change, or the outcome of a sync.
  6. Your system processes this payload to update data or trigger workflows.

Available Webhook Events

Propexo offers several webhook event types, each with its own purpose and payload format:

  • Job Failure – Indicates an integration failed to retrieve data after multiple retry attempts. Rare but important for troubleshooting sync issues.
  • Sync Complete – Sent when a full data sync completes (not including the first sync).
  • First Sync Complete – Sent when the initial full data sync finishes. Useful for ensuring your system is ready for ongoing updates.
  • Data New – Sent when a new record is created for your subscribed object (e.g., residents, applicants). Includes a record ID that can be used to retrieve the full record.
  • Data Update – Sent when an existing record changes. Includes a record ID and a diff showing previous and new values.

A breakdown of each webhook is available in the Webhook Details section of our documentation.

Delivery & Retries

Propexo expects your webhook endpoint to return a 2xx response to confirm successful delivery.

For non-2xx responses, each webhook goes into a retry cycle:

  • Retries occur every 15 minutes.
  • A maximum of 10 retries will be attempted.
  • This means a webhook can retry for up to 150 minutes (2.5 hours) before being dropped.

Details

Some webhook topics require special consideration:

  • Sequencing & Data Hydration – Some integrations send partial data first, then follow with more complete data. This means you may need to handle staged updates or make additional API calls after receiving a webhook.
  • Security: Signed Payloads – All webhook payloads are signed by Propexo so you can verify they come from us and not a third party. The signature is included in the propexo-signature header, and your secret can be found in the Webhooks settings in the dashboard.

Next Steps

Once you understand the basics, you can:

  • Configure your webhooks in the Propexo dashboard.
  • Choose the events most relevant to your use case.
  • Implement handling for specific webhook types.
  • Add security checks to verify webhook authenticity.

NOTE: webhooks are added to a queue and may not be sent as soon as the data change is registered during the syncing process. Webhooks on sandbox integrations are provided with fewer resources and therefore may face mroe significant delays before being sent. While Propexo does not guarantee webhook delivery times, we recommend using production integrations to receive them more quickly.