Webhooks Overview

Webhooks push Hawzu events to your own endpoint in real time. Subscribe a URL to a project’s events and Hawzu POSTs a signed JSON payload whenever one of those events fires — useful for building integrations, notifications, dashboards, or syncing to other systems.

How a delivery works

Each delivery is an HTTP POST whose body is a JSON envelope:

{
  "event": "defect.status_changed",
  "workspace_id": "ws_…",
  "project_id": "prj_…",
  "timestamp_millis": 1717000000000,
  "data": { "defect_code": "BUG-42", "from": "Open", "to": "In Progress", "actor": "qa@acme.com" }
}

with these headers:

Header	Value
X-Hawzu-Event	the event name, e.g. defect.status_changed
X-Hawzu-Signature	sha256=<hex> — HMAC-SHA256 of the raw request body, keyed by the subscription’s signing secret
Content-Type	application/json

See Events for every event and the data shape it delivers.

Verifying the signature

Every delivery is signed so you can confirm it really came from Hawzu. Compute HMAC-SHA256 over the raw body bytes using your subscription’s signing secret (the whsec_… value shown once at creation) and compare it — in constant time — with the X-Hawzu-Signature header.

import hashlib, hmac

def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Caution

The signing secret is shown only once, right after you create a webhook — copy it then. Sign over the exact raw bytes you receive, not a re-serialized object, or the digest won’t match.

Where webhooks are managed

A webhook always belongs to one project and fires only for that project’s events. You can manage subscriptions at two levels — both act on the same webhooks:

• Project Settings → Webhooks — the webhooks for that one project. Available to project managers (and workspace managers).
• Workspace Settings → Webhooks — every webhook across all the workspace’s projects in one place, with a Project column. Available to the owner and workspace managers.

See Managing webhooks for the full lifecycle.

Using the API instead

Subscriptions can also be created, listed, and deleted programmatically via the automation API at /api/v1/workspace/{workspace_id}/project/{project_id}/webhooks. Full request/response schemas, a Try-It console, and authentication details are in the API Reference.

Next steps

• Managing webhooks — create, test, enable/disable, delivery history.
• Events — the events you can subscribe to and their payloads.