HOUSING-iQHousing management system

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

  1. In the staff console, open More, then API and webhooks, and add your endpoint's https address.
  2. 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.
  3. Copy the signing secret (whsec_...). It is shown once; you can make a new one at any time.
  4. Press Send a test event. A ping event 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 id to ignore repeats, and created_at or the record's updated_at to 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

EventWhen
pingA test event sent from the staff console.
property.createdA record was created.
property.updatedA record changed.
property.deletedA record was removed (deleted_at set).
tenant.createdA record was created.
tenant.updatedA record changed.
tenancy.createdA record was created.
tenancy.updatedA record changed.
tenancy.deletedA record was removed (deleted_at set).
repair.createdA record was created.
repair.updatedA record changed.
repair_event.createdA record was created.
repair_event.updatedA record changed.
complaint.createdA record was created.
complaint.updatedA record changed.
case.createdA record was created.
case.updatedA record changed.
appointment.createdA record was created.
appointment.updatedA record changed.
rent_account.createdA record was created.
rent_account.updatedA record changed.
rent_transaction.createdA record was created.
rent_transaction.updatedA record changed.
asb_report.createdA record was created.
asb_report.updatedA record changed.
inspection.createdA record was created.
inspection.updatedA record changed.
void.createdA record was created.
void.updatedA record changed.
compliance_certificate.createdA record was created.
compliance_certificate.updatedA record changed.
document.createdA record was created.
document.updatedA record changed.
notice.createdA record was created.
notice.updatedA record changed.
notice.deletedA record was removed (deleted_at set).
checkin.createdA record was created.
checkin.updatedA record changed.

Subscribe to a whole kind with a wildcard such as repair.*.