Webhooks

Integrate Kuviq with external systems using webhooks.

Overview

Webhooks allow Kuviq to:

• Send data to external systems
• Trigger external workflows
• Integrate with other tools
• Enable custom automation

How Webhooks Work

The Process

1. Event occurs in Kuviq
2. Webhook triggered
3. Data sent to your URL
4. External system processes
5. Response received

Webhook Payload

Data sent as JSON:

{
  "event": "inspection.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "inspectionId": "abc123",
    "itemId": "item456",
    "result": "passed",
    "inspector": {
      "id": "user789",
      "name": "John Smith"
    }
  }
}

Creating Webhooks

Setup Steps

1. Go to Admin > Integrations
2. Click Webhooks or Add Webhook
3. Configure settings
4. Save and activate

Configuration Options

Setting	Description
Name	Descriptive name
URL	Endpoint to receive data
Events	Which events trigger
Secret	For signature verification
Active	Enable/disable

Webhook Events

Inspection Events

Event	Description
inspection.created	New inspection started
inspection.completed	Inspection finished
inspection.failed	Inspection result is fail
inspection.passed	Inspection result is pass

Item Events

Event	Description
item.created	New item added
item.updated	Item modified
item.deleted	Item removed
item.status_changed	Status changed

Corrective Action Events

Event	Description
action.created	New action created
action.updated	Action modified
action.completed	Action completed
action.overdue	Action past due

User Events

Event	Description
user.created	New user added
user.updated	User modified
user.deactivated	User deactivated

Payload Formats

Inspection Completed

{
  "event": "inspection.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "insp_123",
    "item": {
      "id": "item_456",
      "name": "Fire Extinguisher A1",
      "type": "Fire Extinguisher"
    },
    "template": {
      "id": "tmpl_789",
      "name": "Monthly Fire Safety"
    },
    "result": "passed",
    "inspector": {
      "id": "user_012",
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "location": {
      "id": "loc_345",
      "name": "Building A"
    },
    "completedAt": "2024-01-15T10:30:00Z",
    "elements": [
      {
        "name": "Pressure Check",
        "result": "pass",
        "value": "OK"
      }
    ]
  }
}

Item Status Changed

{
  "event": "item.status_changed",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "id": "item_456",
    "name": "Fire Extinguisher A1",
    "previousStatus": "available",
    "newStatus": "needs_attention",
    "reason": "Failed inspection",
    "changedBy": {
      "id": "user_012",
      "name": "Jane Doe"
    }
  }
}

Corrective Action Created

{
  "event": "action.created",
  "timestamp": "2024-01-15T11:05:00Z",
  "data": {
    "id": "action_678",
    "title": "Recharge fire extinguisher",
    "priority": "high",
    "item": {
      "id": "item_456",
      "name": "Fire Extinguisher A1"
    },
    "assignee": {
      "id": "user_901",
      "name": "Bob Wilson"
    },
    "dueDate": "2024-01-18",
    "inspection": {
      "id": "insp_123"
    }
  }
}

Security

Signature Verification

Verify webhooks are from Kuviq:

1. Set a secret when creating webhook
2. Kuviq signs each request
3. Verify signature on receipt

Signature Headers

Each webhook request includes security headers:

X-Webhook-Signature: sha256=<HMAC-SHA256 hash>
X-Webhook-Timestamp: <ISO 8601 timestamp>
Content-Type: application/json

Verification Code Example

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

HTTPS Required

• All webhook URLs must use HTTPS
• HTTP URLs rejected
• Self-signed certificates not supported

Managing Webhooks

Viewing Webhooks

1. Go to Admin > Integrations
2. View webhook list
3. See status and activity

Webhook Details

Field	Description
Name	Webhook identifier
URL	Target endpoint
Events	Subscribed events
Status	Active/Inactive
Last triggered	Recent activity
Success rate	Delivery success

Editing Webhooks

1. Click on webhook
2. Click Edit
3. Modify settings
4. Save

Deactivating

1. Find webhook
2. Toggle Active off
3. Or click Deactivate

Deleting

1. Find webhook
2. Click Delete
3. Confirm

Testing Webhooks

Send Test Webhook

Test your endpoint configuration:

1. Go to Admin > Integrations > Webhooks
2. Find your webhook endpoint
3. Click the Test button
4. View the test result

Test Result

The test shows:

Result	Meaning
✅ Success	Endpoint responded with 2xx status
❌ Failed	Endpoint returned error or timed out
Response code	HTTP status code returned
Response time	How long the request took

Test Payload

Test webhooks send a sample payload:

{
  "event": "test.webhook",
  "timestamp": "2024-01-15T10:30:00Z",
  "isTest": true,
  "data": {
    "message": "This is a test webhook from Kuviq",
    "endpointId": "endpoint_123",
    "organizationId": "org_456"
  }
}

Test Endpoints for Development

Use these services during development:

• webhook.site - Free webhook testing
• requestbin.com - Inspect webhook payloads
• ngrok - Expose local endpoints for testing

Delivery & Retries

Delivery Expectations

• Timeout: 30 seconds
• Expected response: 2xx status
• Retry on failure

Retry Policy

Failed webhooks use exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	15 minutes
4th retry	1 hour
5th retry	4 hours

After 5 failures:

• Webhook event marked as failed
• Available for manual retry
• Admin can view failure details in event log

Response Handling

Response	Action
2xx	Success, no retry
4xx	Failure, no retry (client error)
5xx	Retry (server error)
Timeout	Retry

Webhook Event Log

Accessing the Event Log

1. Go to Admin > Integrations > Webhooks
2. Click Event Log tab
3. View all webhook delivery history

Event Log Dashboard

The event log shows:

Metric	Description
Pending	Events waiting to be delivered
Completed	Successfully delivered events
Failed	Events that failed after all retries
In Progress	Events currently being processed or retrying

Event Details

Each entry shows:

• Event type: The webhook event that triggered
• Status: pending, processing, completed, failed, retrying
• Attempts: Number of delivery attempts
• Created: When the event was created
• Processed: When delivery completed (or last attempt)
• Error message: Details if delivery failed

Filtering Events

Filter the event log by:

• Status: All, Pending, Processing, Completed, Failed, Retrying
• Auto-refreshes every 30 seconds

Manual Retry

For failed events:

1. Find the failed event in the log
2. Click the Retry button
3. Event is requeued for immediate delivery
4. Monitor the status update

Common Integrations

Slack Notifications

Send to Slack channel:

1. Create Slack incoming webhook
2. Add webhook URL to Kuviq
3. Format payload for Slack

Microsoft Teams

Send to Teams channel:

1. Create Teams incoming connector
2. Add connector URL
3. Configure payload format

Custom Applications

Receive in your app:

1. Create endpoint in your app
2. Add URL to Kuviq
3. Process incoming data

Zapier Integration

Connect via Zapier:

1. Use Zapier's webhook trigger
2. Create Zap workflow
3. Connect to other apps

Best Practices

Endpoint Design

1. Respond quickly - Process async if needed
2. Return 2xx - Even if processing later
3. Handle duplicates - Same event may retry
4. Validate signature - Verify authenticity
5. Log requests - For debugging

Error Handling

1. Return appropriate status codes
2. Don't expose internal errors
3. Implement retry logic (for your calls)
4. Monitor for failures

Performance

1. Keep processing fast
2. Queue heavy processing
3. Don't block on external calls
4. Handle bursts gracefully

Troubleshooting

Not Receiving Webhooks

Check:

1. Webhook is active
2. Events are configured
3. URL is correct
4. Endpoint is accessible
5. Firewall allows traffic

Invalid Signature

Check:

1. Secret matches exactly
2. Payload not modified
3. Correct hashing algorithm
4. Encoding is correct

Frequent Failures

Check:

1. Endpoint availability
2. Response time (under 30s)
3. Response status codes
4. Server capacity

Debugging Tips

1. Use webhook logging
2. Test with simple endpoints
3. Check server logs
4. Verify payload format

Rate Limits

Limits

Limit	Value
Webhooks per org	25
Events per webhook	Unlimited
Requests per minute	1000

Handling Limits

If hitting limits:

• Consolidate webhooks
• Filter events more specifically
• Contact support for increases

Next Steps

• Automation Rules - Event-based automation
• Email Notifications - Built-in notifications
• API Documentation - Full API reference