Webhook Documentation

Learn how to configure webhooks to receive real-time alerts from Leicbit

Overview

Leicbit webhooks allow you to receive real-time notifications when security events are detected on your monitored domains. Instead of checking for alerts manually, webhooks automatically send HTTP POST requests to your specified endpoint whenever new security incidents are found.

Real-time Notifications

Receive instant alerts when credential theft or security breaches are detected on your domains.

Secure Delivery

All webhook requests are signed and verified to ensure data integrity and authenticity.

Easy Integration

Simple setup process with comprehensive documentation and testing tools.

Detailed Information

Each webhook contains comprehensive data about the security event for immediate action.

Setup Guide

Follow these steps to configure webhooks for your Leicbit account:

Prerequisite: You need an active Leicbit account with at least one monitored domain.

Step 1: Access Settings

Log in to your Leicbit dashboard
Navigate to Settings in the main menu
Click on the Integration tab

Step 2: Configure Webhook

Enable the webhook by checking the "Enable Webhook" checkbox
Enter your webhook URL in the "Webhook URL" field
Click "Test Webhook" to verify the connection
Click "Save Settings" to activate the webhook

Success! Your webhook is now active and will receive notifications for all security events.

Webhook URL Requirements

Must be a valid HTTPS URL (HTTP is not supported for security reasons)
Should be publicly accessible from the internet
Must respond with HTTP 200 status code to acknowledge receipt
Should respond within 10 seconds to avoid timeout

Webhook Payload

Each webhook request contains detailed information about the security event. Here's the structure of the payload:

{ "event_id": "evt_1234567890abcdef", "event_type": "credential_theft_detected", "timestamp": "2024-01-15T10:30:00Z", "domain": { "id": "dom_1234567890abcdef", "name": "example.com", "description": "Company main website" }, "alert": { "id": "alt_1234567890abcdef", "severity": "high", "title": "Credential Theft Detected", "description": "Compromised credentials found for example.com", "details": { "email_count": 150, "password_count": 150, "source": "data_breach", "breach_date": "2024-01-10T00:00:00Z" } }, "user": { "id": "usr_1234567890abcdef", "email": "[email protected]" }, "webhook_id": "whk_1234567890abcdef" }

Payload Fields

Field	Type	Description
`event_id`	string	Unique identifier for this webhook event
`event_type`	string	Type of security event (see Event Types section)
`timestamp`	ISO 8601	When the event occurred
`domain`	object	Information about the affected domain
`alert`	object	Detailed alert information
`user`	object	Account information
`webhook_id`	string	Identifier for your webhook configuration

Event Types

Leicbit sends different types of events based on the security incidents detected:

credential_theft_detected

Triggered when: Compromised credentials are found for your domain

Severity: High

Action Required: Immediate password reset and security review

domain_compromise_suspected

Triggered when: Suspicious activity is detected on your domain

Severity: Medium

Action Required: Investigation and monitoring

monitoring_started

Triggered when: Domain monitoring is activated

Severity: Info

Action Required: None - confirmation only

threat_resolved

Triggered when: A previously detected threat is resolved

Severity: Info

Action Required: None - status update

Security

Leicbit implements several security measures to ensure the integrity and authenticity of webhook requests:

HTTPS Only

All webhook requests are sent over HTTPS to ensure data encryption in transit. HTTP endpoints are not supported.

Request Verification

Each webhook request includes a signature header that you can use to verify the request came from Leicbit:

X-Leicbit-Signature: t=1234567890,v1=abc123def456...

Verification Process

To verify a webhook request:

Extract the timestamp and signature from the X-Leicbit-Signature header
Concatenate the timestamp and request body
Generate HMAC-SHA256 using your webhook secret
Compare the generated signature with the received signature

Important: Always verify webhook signatures in production to prevent unauthorized requests.

Testing

Leicbit provides built-in testing tools to verify your webhook configuration:

Test Webhook Button

Use the "Test Webhook" button in your settings to send a test payload to your endpoint:

{ "event_id": "test_1234567890", "event_type": "test_webhook", "timestamp": "2024-01-15T10:30:00Z", "domain": { "id": "test_domain", "name": "test.example.com", "description": "Test domain for webhook verification" }, "alert": { "id": "test_alert", "severity": "info", "title": "Test Webhook", "description": "This is a test webhook to verify your endpoint configuration", "details": { "test": true, "message": "If you receive this, your webhook is working correctly" } }, "user": { "id": "test_user", "email": "[email protected]" }, "webhook_id": "test_webhook" }

Expected Response

Your endpoint should respond with:

HTTP Status: 200 OK
Response Time: Less than 10 seconds
Content-Type: application/json (optional)

Success Indicators: You'll see a green success message in the settings page when the test is successful.

Troubleshooting

Common issues and their solutions:

Cause: Your webhook endpoint is not accessible from the internet.
Solution: Ensure your endpoint is publicly accessible and not behind a firewall that blocks incoming requests.

Cause: Your endpoint is encountering an internal error when processing the webhook.
Solution: Check your server logs for errors and ensure your endpoint can handle the webhook payload format.

Cause: Your endpoint is taking too long to respond.
Solution: Optimize your webhook handler to respond quickly. Consider processing the webhook asynchronously if needed.

Cause: Webhook may be disabled or misconfigured.
Solution: Check that webhooks are enabled in your settings and the URL is correct. Test the webhook to verify it's working.

Examples

Here are some examples of how to handle webhooks in different programming languages:

Node.js Example

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

app.use(express.json());

app.post('/webhook', (req, res) => {
    // Verify webhook signature
    const signature = req.headers['x-leicbit-signature'];
    const body = JSON.stringify(req.body);
    const expectedSignature = crypto
        .createHmac('sha256', process.env.WEBHOOK_SECRET)
        .update(body)
        .digest('hex');
    
    if (signature !== `v1=${expectedSignature}`) {
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Process the webhook
    const { event_type, alert, domain } = req.body;
    
    switch (event_type) {
        case 'credential_theft_detected':
            console.log(`🚨 CRITICAL: Credential theft detected for ${domain.name}`);
            // Send to Slack, email, etc.
            break;
        case 'domain_compromise_suspected':
            console.log(`⚠️ WARNING: Suspicious activity on ${domain.name}`);
            break;
        default:
            console.log(`ℹ️ INFO: ${event_type} event received`);
    }
    
    res.status(200).json({ received: true });
});

app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
});
                    

Python Example

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # Verify webhook signature
    signature = request.headers.get('X-Leicbit-Signature')
    body = request.get_data()
    
    expected_signature = hmac.new(
        os.environ['WEBHOOK_SECRET'].encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    
    if signature != f'v1={expected_signature}':
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Process the webhook
    data = request.json
    event_type = data.get('event_type')
    alert = data.get('alert')
    domain = data.get('domain')
    
    if event_type == 'credential_theft_detected':
        print(f"🚨 CRITICAL: Credential theft detected for {domain['name']}")
        # Send notification to your team
    elif event_type == 'domain_compromise_suspected':
        print(f"⚠️ WARNING: Suspicious activity on {domain['name']}")
    
    return jsonify({'received': True})

if __name__ == '__main__':
    app.run(port=5000)
                    

PHP Example

 'Invalid signature']);
    exit;
}

// Process webhook
$data = json_decode($body, true);
$event_type = $data['event_type'] ?? '';
$alert = $data['alert'] ?? [];
$domain = $data['domain'] ?? [];

switch ($event_type) {
    case 'credential_theft_detected':
        error_log("🚨 CRITICAL: Credential theft detected for " . $domain['name']);
        // Send notification
        break;
    case 'domain_compromise_suspected':
        error_log("⚠️ WARNING: Suspicious activity on " . $domain['name']);
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);
?>
                    

Need Help?

If you need assistance with webhook configuration or have questions about the integration:

Documentation

Check our comprehensive API documentation for more details.

View API Docs

Support

Contact our support team for personalized assistance.

Contact Support

Table of Contents