Integrations — Testing Your Connection

Every integration in Settings → API & webhooks has a self-serve way to prove it actually works before you rely on it — no waiting for a real survey to finalize, no guessing whether your endpoint or credentials are right. Written for the person on your side who'll actually wire this up: a housing association IT contact, or your CMS vendor's integration developer. Tiered — Basics for what to click, Deep dive for what "success" looks like, Technical for verifying signatures and debugging failures.

Basics — what to test, and where

Integration	Where	Test affordance
Webhook	Settings → API & webhooks → Webhook (push to your CMS)	Send test event button
REST API	Settings → API & webhooks → REST API	Quick start curl examples + sample payload viewer
HACT payload shape	Settings → API & webhooks → REST API	View sample HACT payload
EDI flat-file (CSV)	Settings → API & webhooks → EDI flat-file (CSV)	Manual date-range Export CSV run
SFTP server	Settings → SFTP servers	Test connection button
SMTP (statutory email)	Settings → Notifications (or wherever your SMTP config lives)	Test connection button
AI provider key	Settings → AI	Test connection button

All of these are org-admin actions, live server-side, and never touch or modify real evidence.

Deep dive — one integration at a time

Webhook

Save a webhook URL first (HTTPS only).
Click Send test event. This fires a real, signed test.ping event at your saved URL right now — no queue, no waiting for the next survey to finalize.
Read the result inline:

Green, "Delivered · HTTP 2xx · Nms" — your endpoint accepted the POST. You're done.
Red, with an error or non-2xx status — see Common failure causes below.

Expand View sample payload & signature headers sent to see the exact JSON body and x-hsp-signature/x-hsp-event headers your endpoint just received — hand this straight to your dev team so they can build signature verification against real bytes, not guesswork.

The test event is signed with your real signing secret, using the same HMAC code path every production survey.finalized delivery uses — so a passing test is a genuine, not simulated, proof that delivery and signature verification both work end-to-end.

The payload is clearly marked "sample": true and carries no real evidence — your endpoint should accept it exactly as it would accept a production event, then discard it (or route it to a test log) based on that flag.

REST API

Mint an API key with the scopes you need (Settings → API & webhooks → REST API).
Expand Quick start for your organisation's base URL and ready-to-run curl examples for GET /v1/surveys and GET /v1/work-orders — copy one, swap in your real key, and run it from a terminal.
A 200 with a JSON body (even an empty surveys: [] array on a brand-new org) confirms auth, scopes and network access all work.
Expand View sample HACT payload to see the exact shape a real, finalized survey returns — every field populated at once with synthetic data — so you can build a parser before real evidence exists.

HACT payload shape

The sample payload viewer (inside the REST API card) renders the platform's toHact() mapping applied to a synthetic survey, property and work order. It's generated entirely client-side in your browser — nothing is sent to or read from any server for this view. Use it to confirm your CMS's ingest mapping (measurements, hazards, evidence, the Awaab's Law statutory block) matches what you expect before the first real payload arrives.

EDI flat-file (CSV)

The nightly export (02:00 UK) is the production path, but you don't have to wait for it:

Pick a short date range (a day or two of test data, or even a range with zero records — that's a valid test too).
Click Export CSV. This runs the exact same export code the nightly schedule uses, synchronously, and opens the resulting file.
Confirm the column layout matches what your ingest expects, and that the download link works — it expires after 7 days, same as the nightly drop.

SFTP server

Add a server (Settings → SFTP servers) and, if using a key, mint one and install the public half on your server.
Click Test connection. This runs a real 4-step handshake — connect, negotiate the host key, authenticate, then a read-only check of the remote path — and never writes a file.
Each step shows pass/fail inline. On the first successful test, your server's host-key fingerprint is shown for you to confirm and pin; from then on, a changed fingerprint fails the test closed rather than connecting anyway.

SMTP (statutory deadline emails)

Save your organisation's SMTP host, port, credentials and from-address.
Click Test connection (Settings → Notifications). This sends a real test email to your own signed-in account's email address using the saved config — the fastest way to prove host/port/auth/TLS all work without touching a live tenant notification.
Check your inbox (and spam folder) for "HousingSurvey Pro — SMTP test email". Arrival confirms the full chain: connection, auth, and delivery.

AI provider key

Pick a provider and paste your own API key (Settings → AI).
Click Test connection. The platform asks your provider to reply with a single fixed word using your key and resolved model, and reports the result — Connected · provider · model on success, or the provider's own error message (shortened) on failure.
A pass here means AI-assisted features (photo analysis, polish, summaries) will work; a fail means to double-check the key and any provider-side billing/quota setup before relying on them.

Technical — verifying signatures & debugging failures

Verifying a webhook signature

Every webhook delivery — test or production — carries:

x-hsp-signature: the hex-encoded HMAC-SHA256 of the raw request body, keyed with your organisation's signing secret (shown once when you first saved the webhook URL; regenerate by re-saving if you've lost it).
x-hsp-event: the event name (test.ping for test events, survey.finalized and deadline events in production).

Verify it server-side (pseudocode, any language):

expected = hex(hmac_sha256(secret, raw_request_body))
if !constant_time_equals(expected, headers['x-hsp-signature']):
    reject as 401/403 — do not process

Compute the HMAC over the raw bytes of the body exactly as received — re-serializing parsed JSON before hashing will produce a different signature and a false rejection.

Common failure causes

Symptom	Likely cause
Webhook test times out (no response in 10s)	Your endpoint is slow, unreachable, or behind a firewall/VPN that isn't reachable from the public internet — HousingSurvey Pro calls out from europe-west2 (London); check your IP allowlist includes Google Cloud egress ranges for that region, or allow the request generally if you can't pin an IP range.
Webhook test returns a non-2xx status	Your endpoint rejected the request — check its own logs; a 401/403 usually means signature verification failed (see above); a 404 usually means the URL path is wrong.
Webhook signature doesn't match	You're hashing the parsed/re-serialized body instead of the raw bytes; or you copied the wrong secret (each save of the webhook URL can rotate the secret — check you have the latest one).
REST API returns 401	The `Authorization: Bearer` header is missing, malformed, or the key was revoked.
REST API returns 403 "missing scope"	The key wasn't minted with the scope the endpoint needs — mint a new key with the right scopes (existing keys' scopes can't be edited, only revoked and replaced).
REST API returns 404 on a specific record	The id belongs to a different organisation, or doesn't exist / was soft-deleted.
EDI export button stays disabled	Both a "since" and "until" date are required before the button activates.
EDI download link doesn't work	Links expire 7 days after generation — run a fresh export.
SFTP test fails at "tcp-connect"	Host/port unreachable from HousingSurvey Pro's servers (europe-west2) — check the host, port, and any IP allowlist on your side.
SFTP test fails at "handshake" with a fingerprint mismatch	Your server presented a different host key than the one previously pinned — verify the new fingerprint with your IT team out-of-band before re-pinning; never re-pin on trust alone.
SFTP test fails at "auth"	Wrong username/password, or the public key isn't installed (or was removed) in the server account's `authorized_keys`.
SFTP test fails at "stat-remote-path"	The configured remote path doesn't exist, or the account can't access it.
SMTP test doesn't arrive	Wrong host/port/security (TLS vs STARTTLS on the wrong port is the most common cause), or a mail provider blocking unfamiliar app passwords — check your provider's own sent-mail log if available, and your spam folder.
AI test fails with a provider error	Usually an invalid/expired key, or billing not enabled on the provider account — the error message returned is the provider's own, only shortened for display.

Residency & auditing

All test and production traffic for these integrations is served from europe-west2 (London) — no test call ever leaves that region. Every API read/write and every webhook delivery attempt is written to your organisation's append-only, hash-chained audit log, so a test event and a production event are both fully traceable after the fact.

See also: Integrations — Webhooks & API for the full API/webhook reference, Integrations — AI provider keys for AI setup, or back to the help index.