Webhook Configuration

Webhook Configuration

Webhooks allow KyberAccess to send real-time notifications to your external systems whenever specific events occur — such as a visitor checking in, a watchlist hit being detected, or an emergency lockdown being triggered. Instead of repeatedly polling the API for changes, webhooks push data to your server the moment something happens.

This guide covers how to set up, test, secure, and troubleshoot webhooks.

How Webhooks Work

1. You configure a webhook endpoint (a URL on your server).
2. You select which events should trigger the webhook.
3. When a matching event occurs in KyberAccess, an HTTP POST request is sent to your endpoint with the event data.
4. Your server processes the data and returns a 200 response to acknowledge receipt.

Setting Up a Webhook

Step 1: Navigate to Webhook Settings

1. Log in to your KyberAccess dashboard at app.kyberaccess.com.
2. Navigate to Settings from the left sidebar.
3. Click API & Integrations under the Developer section.
4. Select the Webhooks tab.

Step 2: Create a New Webhook

1. Click + Add Webhook.
2. Configure the following fields:
   • Name — A descriptive name (e.g., "CRM Visitor Sync" or "Slack Notifications")
   • Endpoint URL — The HTTPS URL where events will be sent (e.g., https://yourserver.com/webhooks/kyberaccess)
   • Description — Optional notes about the webhook's purpose
3. Click Next to proceed to event selection.

Important: The endpoint URL must use HTTPS. HTTP endpoints are not accepted for security reasons.

Step 3: Select Events

Choose which events should trigger this webhook:

Visitor Events:

• visitor.checked_in — A visitor has checked in
• visitor.checked_out — A visitor has checked out
• visitor.denied — A visitor was denied entry
• visitor.pre_registered — A new pre-registration was created
• visitor.pre_registration_cancelled — A pre-registration was cancelled
• visitor.updated — A visitor record was modified
• visitor.deleted — A visitor record was deleted

Security Events:

• screening.watchlist_hit — A visitor matched a watchlist entry
• screening.bolo_alert — A BOLO alert was triggered
• screening.cleared — A visitor passed all screening checks

Emergency Events:

• emergency.lockdown_activated — A lockdown was triggered
• emergency.lockdown_deactivated — A lockdown was lifted
• emergency.evacuation_activated — Evacuation mode was activated

Document Events:

• document.nda_signed — A visitor signed an NDA/waiver
• document.nda_declined — A visitor declined to sign

Delivery Events:

• delivery.received — A package was logged
• delivery.picked_up — A package was picked up
• delivery.notified — A recipient was notified about a delivery

System Events:

• user.login — A team member logged in
• user.login_failed — A failed login attempt
• settings.updated — System settings were changed

Check the events you want and click Next.

Step 4: Configure Security

1. Signing Secret — KyberAccess generates a unique signing secret for this webhook. Copy it and store it securely.
2. IP Allowlist (optional) — Restrict webhook delivery to specific source IPs from KyberAccess.
3. Click Create Webhook.

Webhook Payload Format

When an event occurs, KyberAccess sends an HTTP POST request to your endpoint with the following structure:

Headers

Content-Type: application/json
X-KyberAccess-Event: visitor.checked_in
X-KyberAccess-Delivery: dlv_abc123
X-KyberAccess-Timestamp: 1705312200
X-KyberAccess-Signature: sha256=a1b2c3d4e5f6...

Body

{
  "id": "evt_001",
  "event": "visitor.checked_in",
  "timestamp": "2025-01-15T09:30:00Z",
  "data": {
    "visitor": {
      "id": "vis_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "purpose": "Meeting"
    },
    "host": {
      "id": "usr_xyz789",
      "name": "John Doe",
      "department": "Engineering"
    },
    "location": {
      "id": "loc_001",
      "name": "Main Office"
    },
    "check_in_time": "2025-01-15T09:30:00Z",
    "badge_number": "V-0042",
    "id_scanned": true,
    "nda_signed": true,
    "screening_status": "cleared"
  },
  "account_id": "acc_001"
}

Verifying Webhook Signatures

To ensure webhook requests genuinely come from KyberAccess, verify the signature included in every request.

Verification Process

1. Extract the X-KyberAccess-Signature header value.
2. Extract the X-KyberAccess-Timestamp header value.
3. Concatenate the timestamp and the raw request body with a period: timestamp.body.
4. Compute an HMAC-SHA256 hash using your webhook's signing secret.
5. Compare your computed hash with the signature from the header.

Node.js Example

const crypto = require('crypto');

function verifyWebhook(req, signingSecret) {
  const signature = req.headers['x-kyberaccess-signature'];
  const timestamp = req.headers['x-kyberaccess-timestamp'];
  const body = JSON.stringify(req.body);
  
  const payload = `${timestamp}.${body}`;
  const expectedSignature = 'sha256=' + 
    crypto.createHmac('sha256', signingSecret)
      .update(payload)
      .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Python Example

import hmac
import hashlib

def verify_webhook(payload, timestamp, signature, signing_secret):
    message = f"{timestamp}.{payload}"
    expected = 'sha256=' + hmac.new(
        signing_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Important: Always use constant-time comparison functions (like timingSafeEqual or compare_digest) to prevent timing attacks.

Retry Policy

If your endpoint fails to respond with a 2xx status code, KyberAccess retries the delivery:

After 5 failed retries, the delivery is marked as failed and no further attempts are made.

Note: Your endpoint must respond within 30 seconds. If processing takes longer, return a 200 immediately and process the event asynchronously.

Testing Webhooks

Built-In Test Tool

1. Go to Settings → API & Integrations → Webhooks.
2. Click on the webhook you want to test.
3. Click the Test button.
4. Select a sample event type from the dropdown.
5. Click Send Test Event.
6. KyberAccess sends a test payload to your endpoint and displays the response.

Using a Testing Service

For development, you can use services like:

• webhook.site — Provides a temporary URL that captures and displays incoming webhooks
• ngrok — Exposes your local development server to the internet
• RequestBin — Captures and inspects HTTP requests

Managing Webhooks

Viewing Delivery Logs

1. Click on a webhook in the Webhooks tab.
2. Select the Deliveries tab.
3. Each delivery shows:
   • Event Type — What triggered the webhook
   • Timestamp — When the event occurred
   • Response Code — Your server's HTTP response code
   • Response Time — How long your server took to respond
   • Status — Delivered, Retrying, or Failed
4. Click on any delivery to see the full request payload and response.

Pausing a Webhook

1. Click the toggle next to the webhook to pause it.
2. Events are not queued while paused — they are skipped entirely.
3. Toggle it back on to resume deliveries.

Editing a Webhook

1. Click the pencil icon next to the webhook.
2. Modify the endpoint URL, events, or security settings.
3. Click Save Changes.

Note: Changing the endpoint URL does not change the signing secret. You can regenerate the secret manually if needed.

Deleting a Webhook

1. Click the trash icon next to the webhook.
2. Confirm the deletion.
3. All delivery history for this webhook is also deleted.

Multiple Webhooks

You can create multiple webhooks for different purposes:

• CRM Integration — Subscribe to visitor.checked_in and visitor.checked_out to sync visitor data with your CRM
• Security Monitoring — Subscribe to screening.watchlist_hit and emergency.* events for your security operations center
• Slack Bot — Subscribe to visitor events to post check-in notifications in Slack
• Analytics Pipeline — Subscribe to all events to feed data into your data warehouse

Each webhook has its own endpoint, events, and signing secret.

Webhook Limits

Troubleshooting

Best Practices

• Respond quickly — Return a 200 status immediately, then process the event in a background job.
• Verify signatures — Always validate the webhook signature to prevent spoofed requests.
• Implement idempotency — Use the delivery ID to handle duplicate deliveries gracefully.
• Monitor delivery logs — Check the delivery logs weekly for failures or high response times.
• Use separate webhooks — Don't subscribe one webhook to every event. Create targeted webhooks for specific integrations.
• Set up alerts — Monitor your webhook endpoint's availability and set up alerts for downtime.