Webhook Setup

Configure webhooks to receive real-time notifications about events.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in the CHeKT platform. Instead of polling for changes, webhooks push data to your server in real-time.

Prerequisites

• HTTPS endpoint (required for production)
• Ability to respond within 5 seconds
• Webhook secret for signature verification

Creating a Webhook Endpoint

Your endpoint must:

• Accept POST requests
• Respond with 200 status on success
• Verify webhook signatures
• Process events asynchronously

Example Endpoint (Express.js)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/chekt', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  // Verify signature
  const isValid = verifySignature(payload, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process event asynchronously
  processEvent(req.body).catch(console.error);

  // Respond immediately
  res.status(200).send('OK');
});

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

  return signature === `sha256=${expected}`;
}

app.listen(3000);

Registering a Webhook

API Endpoint

POST /partner/v1/webhooks

Request Example

curl -X POST https://api.chekt.com/partner/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/chekt",
    "events": [
      "alarm.triggered",
      "alarm.cleared",
      "device.status_changed",
      "site.armed",
      "site.disarmed"
    ],
    "secret": "your_webhook_secret_key"
  }'

Response

{
  "webhook_id": "webhook_abc123",
  "url": "https://your-app.com/webhooks/chekt",
  "events": ["alarm.triggered", "alarm.cleared"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Available Events

Alarm Events

Device Events

Site Events

Webhook Payload

All webhooks include:

{
  "event": "alarm.triggered",
  "webhook_id": "webhook_abc123",
  "timestamp": "2024-01-15T14:20:00Z",
  "data": {
    "alarm_id": "alarm_xyz789",
    "site_id": "site_123",
    "device_id": "device_456",
    "severity": "high",
    "zone": "Front Door"
  }
}

Signature Verification

Python Example

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

Node.js Example

const crypto = require('crypto');

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

  return signature === `sha256=${expected}`;
}

Testing Webhooks

Use the webhook testing endpoint:

curl -X POST https://api.chekt.com/partner/v1/webhooks/webhook_abc123/test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This sends a test event to your endpoint:

{
  "event": "webhook.test",
  "webhook_id": "webhook_abc123",
  "timestamp": "2024-01-15T14:20:00Z",
  "data": {
    "message": "This is a test webhook"
  }
}

Retry Logic

If your endpoint fails to respond with 200:

1. First retry: After 5 seconds
2. Second retry: After 30 seconds
3. Third retry: After 5 minutes
4. Webhook disabled: After 3 consecutive failures

Managing Webhooks

List Webhooks

curl -X GET https://api.chekt.com/partner/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Webhook

curl -X PATCH https://api.chekt.com/partner/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["alarm.triggered", "device.status_changed"]
  }'

Delete Webhook

curl -X DELETE https://api.chekt.com/partner/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Best Practices

• HTTPS Only: Use HTTPS in production
• Signature Verification: Always verify signatures
• Async Processing: Process events asynchronously
• Idempotency: Handle duplicate events gracefully
• Error Logging: Log all webhook failures
• Monitoring: Set up alerts for webhook failures

Troubleshooting

Webhook Not Receiving Events

1. Check webhook status is "active"
2. Verify endpoint is accessible
3. Test with manual trigger
4. Check firewall settings

Signature Verification Failing

1. Ensure using correct secret
2. Verify payload is not modified
3. Check signature format (sha256=...)

Next Steps

• View API Reference
• Error Handling Guide