HousingSurvey Pro Logo
HousingSurveyPRO™

Integrations — Webhooks & API

ProSurvey Apps Limited (company no. 17118570) · Help centre

For teams that want to connect HousingSurvey Pro to their own systems — a housing management system, a data warehouse, a BI tool — the platform offers event webhooks and a programmatic API. Tiered — Basics for what's possible, Deep dive for setup, Technical for developers and integrators.

Basics — connecting your systems

  • Webhooks push a notification to your endpoint when something happens (a survey is sealed, a work order changes stage), so your systems react in real time instead of polling.
  • API lets your systems read data (properties, surveys, work orders) and, on higher tiers, drive workflows programmatically.
  • Both are configured under Settings → API & webhooks by an org admin, and are available on the appropriate plan tier.

Deep dive — setting up

  • API keys: generate a key in Settings → API & webhooks. Treat it like a password — it grants access scoped to your organisation. Rotate or revoke keys at any time; revoking is immediate.
  • Webhook endpoints: register the HTTPS URL your system listens on and select the events you care about. Each delivery is signed so you can verify it genuinely came from HousingSurvey Pro.
  • Testing: every integration on this page has a self-serve test — send a signed test webhook event, run curl against the API with a sample payload viewer, trigger a one-off EDI export, and more. See Integrations — Testing your connection.

Technical — for developers & integrators

  • Auth: API requests authenticate with your organisation-scoped API key; every call is checked against the same server-side security rules as the UI, so an integration can never exceed your organisation's data boundary.
  • Webhook security: deliveries are signed (HMAC over the payload with your secret); verify the signature and reject anything that doesn't match. Handle retries idempotently — treat repeated event IDs as one.
  • Data model: the API exposes the same tenant-scoped entities described in Access control; evidence remains immutable and hash-chained regardless of how it's read.
  • Residency & limits: calls are served in-region (UK); rate limits and the full event catalogue are documented on the Settings → API & webhooks page.

Handling report versions

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. Every version, old and new, stays retrievable and independently hash-chained; nothing is ever overwritten.

  • lineageId is stable across every version of a report — it's the original record's own id. Key your stored reports by lineageId.
  • versionNo is 1-based and increments with each revision. Treat the highest versionNo you've seen for a lineageId as the current version.
  • supersedes holds the id of the version this one replaces — null on the original (version 1).
  • All three fields appear on the survey.finalized webhook payload, on every survey returned by GET /v1/surveys and GET /v1/surveys/:id, and as version_no/supersedes columns in the nightly EDI CSV export.

Example survey.finalized webhook body for a third version of a report:

{
  "event": "survey.finalized",
  "orgId": "org_4b7e1a",
  "at": "2026-07-09T08:12:44.000Z",
  "surveyId": "svy_1e88bb",
  "recordHash": "3f9e2c1a7b…",
  "chainSeq": 12,
  "lineageId": "svy_9f2a01",
  "versionNo": 3,
  "supersedes": "svy_c77d40",
  "estimatedCosts": { "total": 450, "currency": "GBP", "itemCount": 2 }
}

Rollout note: the API surface and webhook event catalogue are expanding; the auth model (org-scoped keys, signed deliveries, rules-enforced access) is fixed. Confirm currently available endpoints and events on your dashboard.

Back to the help index. This completes the help-centre core; every dashboard section and app module now has a guide.

← Back to help centre