Webhooks
HOUSING-iQ sends each change to your systems as it happens, signed so you can check it came from us.
Set up an endpoint
- In the staff console, open More, then API and webhooks, and add your endpoint's https address.
- Choose sandbox (changes made with test keys) or live (real changes, from the app or the API), and the kinds of event to send. Choose none to get everything.
- Copy the signing secret (
whsec_...). It is shown once; you can make a new one at any time. - Press Send a test event. A
pingevent arrives within a minute, and the delivery shows in the console.
Endpoints must be public https addresses. They are sent to from api.housing-iq.com.
What we send
A POST with a JSON event. data.object is the record after the change, in the same shape the API returns; for updates, data.previous_attributes holds the fields that changed, with their old values.
POST /your/endpoint HTTP/1.1
content-type: application/json
user-agent: HOUSING-iQ-Webhooks/1.0 (+https://www.housing-iq.com/developers/webhooks/)
housing-iq-signature: t=1795384832,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
housing-iq-event-id: evt_8c1d3e5f7a9b4c2d8e0f1a3b5c7d9e1f
housing-iq-event-type: repair.updated
{
"id": "evt_8c1d3e5f7a9b4c2d8e0f1a3b5c7d9e1f",
"object": "event",
"type": "repair.updated",
"created_at": "2026-11-24T10:31:02Z",
"livemode": true,
"data": {
"object": {
"object": "repair",
"id": "6f1c2b4e-8a3d-4c55-9e21-3b7d0a9f4c12",
"reference": "REP-0042",
"status": "scheduled",
"scheduled_for": "2026-11-27T10:00:00Z",
"...": "..."
},
"previous_attributes": {
"status": "triaged",
"scheduled_for": null
}
}
}
Sensitive records (cases, ASB reports, check-ins) are sent in full only to endpoints that subscribe to them; the event feed shows them in full only to keys with the sensitive scope.
Check the signature
The housing-iq-signature header is t=<unix time>,v1=<signature>. The signature is an HMAC-SHA256 of <t>.<raw body> with your signing secret, in lowercase hex. Use the raw body exactly as received, compare in constant time, and refuse anything more than five minutes old.
Node.js
import crypto from 'node:crypto';
export function verifyHousingIq(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Python
import hashlib, hmac, time
def verify_housing_iq(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
if abs(time.time() - t) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
C#
using System.Security.Cryptography;
using System.Text;
static bool VerifyHousingIq(string rawBody, string header, string secret)
{
var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
var t = long.Parse(parts["t"]);
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"))).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(parts["v1"]));
}
PHP
function verify_housing_iq(string $rawBody, string $header, string $secret): bool {
$parts = [];
foreach (explode(',', $header) as $p) { [$k, $v] = explode('=', $p, 2); $parts[$k] = $v; }
$t = (int) ($parts['t'] ?? 0);
if (abs(time() - $t) > 300) return false;
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
return hash_equals($expected, $parts['v1'] ?? '');
}
Answers and retries
- Answer with any 2xx status within 10 seconds. Do the work afterwards, in the background.
- Anything else, a timeout or a redirect counts as a failure. We try again after 2, 4, 8, 16 minutes and so on, up to 10 attempts over about a day.
- An event may arrive more than once, and not always in order. Use the event
idto ignore repeats, andcreated_ator the record'supdated_atto keep the newest. - Every delivery, its status code and any error is listed in the staff console for each endpoint.
- If your endpoint is down for longer, read
GET /v1/events?after=from the last event you handled to catch up.
Event types
| Event | When |
|---|---|
ping | A test event sent from the staff console. |
property.created | A record was created. |
property.updated | A record changed. |
property.deleted | A record was removed (deleted_at set). |
tenant.created | A record was created. |
tenant.updated | A record changed. |
tenancy.created | A record was created. |
tenancy.updated | A record changed. |
tenancy.deleted | A record was removed (deleted_at set). |
repair.created | A record was created. |
repair.updated | A record changed. |
repair_event.created | A record was created. |
repair_event.updated | A record changed. |
complaint.created | A record was created. |
complaint.updated | A record changed. |
case.created | A record was created. |
case.updated | A record changed. |
appointment.created | A record was created. |
appointment.updated | A record changed. |
rent_account.created | A record was created. |
rent_account.updated | A record changed. |
rent_transaction.created | A record was created. |
rent_transaction.updated | A record changed. |
asb_report.created | A record was created. |
asb_report.updated | A record changed. |
inspection.created | A record was created. |
inspection.updated | A record changed. |
void.created | A record was created. |
void.updated | A record changed. |
compliance_certificate.created | A record was created. |
compliance_certificate.updated | A record changed. |
document.created | A record was created. |
document.updated | A record changed. |
notice.created | A record was created. |
notice.updated | A record changed. |
notice.deleted | A record was removed (deleted_at set). |
checkin.created | A record was created. |
checkin.updated | A record changed. |
Subscribe to a whole kind with a wildcard such as repair.*.