Skip to main content

Webhook Events Reference

When a webhook is configured in Settings → Webhooks, Kazinex sends an HTTP POST to your endpoint whenever a subscribed event occurs. This page documents every available event, when it fires, and the exact payload shape.

Payload envelope​

Every webhook payload is wrapped in a common envelope:

{
  "event": "workflow.completed",
  "organisation_id": "org_abc123",
  "project_id": "proj_xyz789",
  "timestamp": "2024-03-15T14:32:00.000Z",
  "data": { ... }
}
FieldTypeDescription
eventstringThe event name (see below)
organisation_idstringID of the organisation where the event occurred
project_idstringID of the project (null for org-level events)
timestampISO 8601When the event occurred (UTC)
dataobjectEvent-specific payload (see each event below)

Payload signature verification​

All requests include an X-Kazinex-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook secret. Verify this on your server before processing the payload:

import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Events​

workflow.created​

Fires when a new workflow instance is created (status = Active).

{
  "event": "workflow.created",
  "data": {
    "workflow_id": "wf_001",
    "title": "DRG-001 Rev A Approval",
    "reference": "WF-2024-001",
    "template_id": "tmpl_abc",
    "template_name": "Document For Approval",
    "status": "active",
    "priority": "high",
    "due_date": "2024-04-01",
    "initiator_id": "user_xyz",
    "initiator_name": "Jane Smith",
    "created_at": "2024-03-15T14:32:00.000Z"
  }
}

workflow.completed​

Fires when a workflow instance reaches a terminal state (Completed, Cancelled, or Returned).

{
  "event": "workflow.completed",
  "data": {
    "workflow_id": "wf_001",
    "title": "DRG-001 Rev A Approval",
    "reference": "WF-2024-001",
    "status": "completed",
    "outcome": "approved",
    "completed_at": "2024-03-22T09:15:00.000Z",
    "cycle_time_days": 7,
    "initiator_id": "user_xyz",
    "initiator_name": "Jane Smith"
  }
}

outcome values: approved, approved_with_comments, rejected, cancelled, returned

workflow.step_completed​

Fires when an individual step within a workflow is completed.

{
  "event": "workflow.step_completed",
  "data": {
    "workflow_id": "wf_001",
    "step_id": "step_002",
    "step_name": "Project Engineer Approval",
    "step_type": "approve",
    "action": "approved",
    "actor_id": "user_abc",
    "actor_name": "Tom Brown",
    "comment": "Approved. Good to issue.",
    "completed_at": "2024-03-20T16:00:00.000Z"
  }
}

action values: approved, rejected, reviewed_with_comments, returned_for_revision, delegated, reassigned, terminated

document.created​

Fires when a new document record is created in the Document Register.

{
  "event": "document.created",
  "data": {
    "document_id": "doc_001",
    "document_number": "STR-PLAN-ZA-0001",
    "title": "Ground Floor Structural Layout",
    "type": "drawing",
    "discipline": "STR",
    "zone": "ZA",
    "status": "draft",
    "revision": "P01",
    "created_by_id": "user_xyz",
    "created_by_name": "Jane Smith",
    "created_at": "2024-03-15T10:00:00.000Z"
  }
}

document.status_changed​

Fires when a document's status changes.

{
  "event": "document.status_changed",
  "data": {
    "document_id": "doc_001",
    "document_number": "STR-PLAN-ZA-0001",
    "title": "Ground Floor Structural Layout",
    "previous_status": "under_review",
    "new_status": "approved",
    "revision": "A",
    "changed_by_id": "user_abc",
    "changed_by_name": "Tom Brown",
    "changed_at": "2024-03-22T09:15:00.000Z",
    "workflow_id": "wf_001"
  }
}

transmittal.issued​

Fires when a transmittal is issued (status changes to Issued).

{
  "event": "transmittal.issued",
  "data": {
    "transmittal_id": "trn_001",
    "transmittal_number": "TRN-001",
    "purpose": "for_approval",
    "document_count": 5,
    "recipient_count": 3,
    "issued_by_id": "user_xyz",
    "issued_by_name": "Jane Smith",
    "issued_at": "2024-03-15T14:00:00.000Z"
  }
}

purpose values: for_approval, for_information, for_review, as_requested

transmittal.acknowledged​

Fires when a recipient acknowledges a transmittal.

{
  "event": "transmittal.acknowledged",
  "data": {
    "transmittal_id": "trn_001",
    "transmittal_number": "TRN-001",
    "acknowledged_by_id": "user_def",
    "acknowledged_by_name": "Sarah Lee",
    "acknowledged_at": "2024-03-16T09:30:00.000Z",
    "comment": "Received and distributed to site team.",
    "all_acknowledged": false,
    "acknowledged_count": 1,
    "total_recipients": 3
  }
}

all_acknowledged is true when every To recipient has acknowledged.

Delivery and retries​

AttributeValue
HTTP methodPOST
Content-Typeapplication/json
Timeout10 seconds
Retries3 attempts (1s, 5s, 30s delays)
Failure trackingFailure count shown in Settings → Webhooks

Your endpoint must respond with HTTP 2xx within 10 seconds. Non-2xx or timeouts count as failures.