Webhooks

Webhooks push a notification to your own endpoint the moment something happens in HousingSurvey Pro, so your systems react in real time instead of polling an API.

What it is

A webhook is configured under Settings → API & webhooks by an org admin: register the HTTPS URL your system listens on, and every delivery is signed so you can verify it genuinely came from HousingSurvey Pro. This is a Platform-tier feature, the same tier as the REST API and the EDI export it’s typically used alongside.

Before you start

Your endpoint must accept HTTPS POST requests and be reachable from the public internet.

How to do it

1. Open Settings → API & webhooks and register your endpoint URL.
2. Note the signing secret shown when you save — this is used to verify every delivery and is only shown again if you re-save the URL.
3. Choose the events you care about.
4. Use Send test event to fire a real, signed test.ping event at your endpoint before relying on production traffic — see Testing a connection.
5. Have your endpoint verify the x-hsp-signature header (an HMAC-SHA256 of the raw request body, keyed with your secret) before processing anything, and return a 2xx status once it has accepted the delivery.

How it integrates

The current event catalogue is: survey.finalized, survey.withdrawn, work_order.stage_recorded, work_order.deadline_breached, work_order.deadline_approaching, and test.ping. A delivery that fails is retried on a schedule for up to six attempts before it’s given up on — treat repeated event IDs idempotently, since a retry can arrive after your endpoint already processed the original.

A finalized report can later be revised: the original sealed record is never edited in place, a new sealed record is created that supersedes it. Three fields track this on the payload — lineageId (stable across every version), versionNo (1-based, incrementing per revision) and supersedes (the id of the version this one replaces, null on the original). The same three fields appear on GET /v1/surveys and in the nightly EDI export as version_no/supersedes columns, so your own system can key stored reports by lineageId and always treat the highest versionNo seen as current.

Common problems

• A webhook test times out. Your endpoint is unreachable from the public internet, or sitting behind a firewall — deliveries originate from europe-west2 (London); check your allowlist covers that region’s egress ranges.
• The signature doesn’t match. Compute the HMAC over the raw request body, not a re-serialized copy of the parsed JSON — re-serializing changes the bytes and produces a different hash. Also confirm you’re using the current secret; re-saving the URL rotates it.
• A webhook delivery never arrived. Check the URL is still correct and returning a 2xx status — a non-2xx response is treated as a failure and retried, then eventually given up on after six attempts.