Set Up Webhooks for System Integration

Role: Org Admin
Time: 20–30 minutes
Prerequisites: An external system or service that can receive HTTP POST requests (e.g. your ERP, a Slack integration, a custom API endpoint, or a tool like webhook.site for testing); the endpoint URL must be publicly accessible (not localhost)

Webhooks let Kazinex notify your external systems in real-time when events occur — a workflow completes, a document is approved, a transmittal is acknowledged. This tutorial walks through the full setup and test process.

---

Step 1: Prepare your receiving endpoint

Before configuring Kazinex, you need a URL that can receive webhook payloads.

For testing (recommended first step): Use a free tool like webhook.site to get a temporary URL that displays incoming requests. This lets you inspect the payload before wiring up your real system.

For production: Your endpoint should:

• Accept HTTP POST requests
• Return HTTP 200 OK within 10 seconds (Kazinex marks delivery failed if no response within 10 seconds)
• Be publicly accessible (not behind a firewall or on localhost)
• Optionally: validate the X-Kazinex-Signature header to verify requests are genuine

---

Step 2: Create the webhook in Kazinex

1. Go to Settings → Webhooks.
2. Click New Webhook.
3. Configure the webhook:

Field	Value
Name	Descriptive name (e.g. "ERP Integration — Workflow Events")
Endpoint URL	Your receiving URL (e.g. https://your-system.com/kazinex-webhook)
Secret	A random secret string you choose (e.g. wh_prod_a8f3x...). Store this securely — you'll use it to verify payloads.
Active	Yes

4. Click Save.

---

Step 3: Subscribe to events

After saving, you see the Event Subscriptions panel.

1. Click Add Subscription.
2. Choose which events to subscribe to:

Event	Fires when
workflow.created	A new workflow instance is started
workflow.completed	A workflow instance completes (approved or rejected)
workflow.step_completed	A single step within a workflow completes
document.created	A new document record is created
document.status_changed	A document's status changes (e.g. draft → approved)
transmittal.issued	A transmittal is issued to recipients
transmittal.acknowledged	A transmittal recipient acknowledges receipt

3. Select the events relevant to your integration. For an ERP integration tracking approvals: select workflow.completed and document.status_changed.
4. Click Save Subscriptions.

---

Step 4: Send a test event

1. From the webhook settings page, click Send Test Event.
2. Select an event type (e.g. workflow.completed).
3. Click Send.
4. Kazinex sends a sample payload to your endpoint.

If using webhook.site: Open your webhook.site URL in the browser — you should see the request arrive within seconds. Inspect the headers and body.

Expected payload structure:

{
  "event": "workflow.completed",
  "timestamp": "2024-03-15T10:30:00Z",
  "organisation_id": "org_abc123",
  "project_id": "proj_xyz789",
  "data": {
    "workflow_id": "wf_001",
    "document_id": "doc_001",
    "document_number": "STR-DWG-ZA-0001",
    "status": "completed",
    "outcome": "approved"
  }
}

---

Step 5: Verify the signature (recommended for production)

Kazinex signs every payload using HMAC-SHA256 with your secret. Verify it in your endpoint code to ensure requests are genuine:

import hmac, hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    received = signature_header.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

The signature is in the X-Kazinex-Signature HTTP header as sha256=<hex-digest>.

If signature verification fails, return HTTP 401 — Kazinex will log it as a delivery failure.

---

Step 6: Monitor delivery status

1. Return to Settings → Webhooks → open your webhook.
2. The Delivery Log tab shows recent delivery attempts:

Column	Meaning
Event	The event type fired
Timestamp	When the event occurred
Status	success (2xx response received) or failed (non-2xx or timeout)
Response Code	The HTTP status your endpoint returned
Duration	How long your endpoint took to respond

3. Click any delivery entry to see the full request payload and response.

---

Step 7: Handle delivery failures

If deliveries are failing:

1. Check your endpoint URL — ensure it is correctly spelled and publicly accessible.
2. Check response time — if your endpoint takes more than 10 seconds to respond, Kazinex marks it as failed. Process quickly and return 200 immediately; do any heavy processing asynchronously.
3. Check for server errors — 500 errors mean your endpoint is throwing exceptions. Fix the error handler.
4. Click Retry on a failed delivery to resend the payload without needing to trigger a new event.

---

Verification

Your webhook is working correctly when:

• Test events arrive at your endpoint within 1–3 seconds of clicking Send Test Event
• The Delivery Log shows success status for all deliveries
• Your receiving system handles the payload correctly (for production integrations)
• The signature verification passes (if implemented)

---

What's next

• Webhook Events Reference — full payload schema for all 7 events
• Webhooks Guide — advanced configuration, retry behaviour, failure tracking
• Settings: Webhook Settings — managing webhooks in the Settings tab