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": "credentials.detected",
  "total_new_alerts": 12,
  "domains": [
    { "domain": "example.com", "new_alerts": 9 },
    { "domain": "shop.example.com", "new_alerts": 3 }
  ],
  "detected_at": "2026-01-15T10:30:00+00:00"
}

The webhook is sent at the end of a monitoring scan that found new leaked credentials, summarizing what was detected across your monitored domains. For full per-credential detail, use the dashboard or the Findings API.

Payload Fields

Field	Type	Description
`event`	string	Event name. Currently always credentials.detected.
`total_new_alerts`	integer	Total number of new leaked-credential alerts in this scan.
`domains`	array	Per-domain breakdown: { "domain", "new_alerts" }.
`detected_at`	ISO 8601	When the scan completed (UTC).

Event Types

Leicbit currently sends a single webhook event. More may be added over time; always switch on the event field rather than assuming a fixed set.

credentials.detected

Triggered when: A monitoring scan finds new leaked credentials for one or more of your domains.

Payload: Scan summary — total_new_alerts plus a per-domain breakdown.

Action Required: Review the new alerts in your dashboard and rotate affected credentials.

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:

Webhook test fails with "Connection refused"

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.

Webhook returns HTTP 500 error

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.

Webhook times out after 10 seconds

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

Not receiving webhook notifications

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) => {
    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' });
    }

    const { event_type, alert, domain } = req.body;
    // Handle event…
    res.status(200).json({ received: true });
});

app.listen(3000);

Python Example

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

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Leicbit-Signature')
    body = request.get_data()
    expected = hmac.new(
        os.environ['WEBHOOK_SECRET'].encode(), body, hashlib.sha256
    ).hexdigest()
    if signature != f'v1={expected}':
        return jsonify({'error': 'Invalid signature'}), 401
    # Handle event…
    return jsonify({'received': True})

PHP Example

<?php
$secret = $_ENV['WEBHOOK_SECRET'];
$signature = $_SERVER['HTTP_X_LEICBIT_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
$expected = 'v1=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($signature, $expected)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Invalid signature']));
}
// Handle event…
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