Skip to main content
DevelopersAPI reference

Webhooks

Webhook integration guide

SmartComply webhooks let partner systems react to compliance events as they happen: test submissions, permit exceedances, notices, inspections, report certifications, and partner lifecycle updates.

Start with the quickstartRegister an endpoint, save the secret, and send a test event.Browse event typesReview the full event catalog and representative payloads.

Event envelope

Every delivery uses a consistent JSON envelope. The type field tells you which event occurred, created_at records when SmartComply emitted it, and data contains the event-specific payload.

{
  "id": "evt_8f3a2c1b6e9d4a07",
  "type": "test.submitted",
  "created_at": "2026-05-05T14:30:00.000Z",
  "data": {
    "test_id": "bft_a1b2c3d4",
    "result": "pass",
    "facility_name": "City Hall Annex"
  }
}

Signature verification

SmartComply signs each request with the endpoint's signing secret. Verify the x-smartcomply-signature header against the raw request body before parsing JSON, and reject timestamps older than five minutes to reduce replay risk.

x-smartcomply-signature: t=1777989600,v1=6c3f9e...

signed_payload = timestamp + "." + raw_request_body
expected = HMAC_SHA256(endpoint_signing_secret, signed_payload)

Delivery and retries

Return a 2xx response as soon as the event is accepted. Non-2xx responses and network failures are retried with backoff, so receivers should be idempotent and deduplicate using id.

  • • Store processed event IDs before kicking off slow work.
  • • Keep webhook handlers fast; move downstream work to a queue.
  • • Log signature failures without logging secrets or full payloads.

Recommended path

  1. 1. Register a webhook endpoint and copy the signing secret.
  2. 2. Implement raw body signature verification in your receiver.
  3. 3. Send a test event, inspect the delivery log, then subscribe to production events.
QuickstartEvent catalog