Skip to main content

ThreatLens Event Subscribing Guide

Disclaimer

This document contains confidential information from Bugsmirror Research Pvt. Ltd. By accessing this document you agree to keep the information in strict confidence. Do not copy, disclose, or distribute it without proper authorisation or written consent from Bugsmirror Research Pvt. Ltd. If you are not the intended recipient, please delete or shred all the copies of the document with you and inform the sender immediately. Be aware that any unauthorised disclosure, copying, or distribution of the contents of this document is strictly prohibited.

1. Introduction​

Welcome to the ThreatLens Webhook Integration Guide. Our system provides real-time security threat intelligence. To ensure your applications receive these critical alerts instantly and securely, ThreatLens utilizes a robust webhook architecture to push data directly to your infrastructure.

2. Architecture & Flow​

The webhook delivery lifecycle operates in three real-time phases:

  • Detection: The ThreatLens engine detects a security threat relevant to your organization's monitored assets.
  • Dispatch: The alert is immediately generated and published to our secure messaging queue.
  • Delivery: Our system fires an HTTPS POST request containing the threat data to your registered Webhook URL.

3. Webhook Endpoint Requirements​

To successfully integrate with ThreatLens, your engineering team must expose a Webhook Endpoint that meets the following technical specifications:

  • Protocol: Must be a secure HTTPS endpoint (e.g., https://api.yourcompany.com/v1/threat-receiver).
  • HTTP Method: POST
  • Response: Your server must acknowledge receipt by returning an HTTP status code 200 OK within 10 seconds. (Note: Other success codes like 201 or 202 are not accepted and will trigger a retry)
note

The webhook URL must not exceed 1024 bytes (1 KB). Larger values are not supported.

4. Request Headers​

Every webhook event dispatched by ThreatLens will include the following standardized headers. Your system should parse these to handle the payload and authenticate the request.

HeaderTypeDescription
Content-TypeStringWill always be application/json.
X-AUTHENTICATIONStringA pre-shared cryptographic secret token used to verify that the request originated from ThreatLens.
⚠️ Note: The X-AUTHENTICATION token must not exceed 1024 bytes (1 KB). Tokens larger than this limit are not supported and will result in the request being rejected.
Content-EncodingStringThe request body is gzip-encoded, Server must handle it explicitly.

5. Message Payload Schema​

Threat events are delivered in the body of the POST request as a JSON object.

Schema Definition​

FieldTypeDescription
DeviceIdStringThe unique identifier of the device where the threat was detected.
ThreatIdIntegerThe internal classification code/ID for the specific threat detected.
EventDateIntegerThe Epoch UTC timestamp (in milliseconds) recording exactly when the threat occurred.

Example JSON Payload​

{
  "DeviceId": "nkjnkjdnfkjds",
  "ThreatId": 61007,
  "EventDate": 1775068199000
}

6. Security & Verification​

Security is critical when receiving automated security events. We strongly require implementing the following guardrails:

  1. Require HTTPS: Ensure your endpoint enforces TLS/SSL encryption to prevent man-in-the-middle (MITM) attacks.
  2. Validate the Secret Token: Your endpoint should check the X-AUTHENTICATION header on every incoming request. If the token is missing or does not match your provided secret, your system must reject the request with a 401 Unauthorized or 403 Forbidden status code.

7. Retry Policy & Delivery Guarantees​

In the event of network instability or endpoint downtime, ThreatLens ensures high availability of your alerts through an automated retry mechanism.

Retry Triggers:​

  • Timeout: Your server fails to respond within 10 seconds.
  • Failure Codes: Your server responds with any non-200 HTTP status code (including other 2xx codes or 5xx errors).

Retry Strategy:​

  • ThreatLens utilizes an exponential backoff mechanism.
  • We will attempt to deliver the payload up to 5 times before marking the event as failed.

8. Example cURL Request​

curl -X POST https://api.yourcompany.com/v1/threat-receiver \
  -H "Content-Type: application/json" \
  -H "X-AUTHENTICATION: <your-secret-token>" \
  -d '{
    "DeviceId": "nkjnkjdnfkjds",
    "ThreatId": 61007,
    "EventDate": 1775068199000
  }'

9. Implementation Checklist​

Please run through this checklist before moving your webhook integration to production:

  • Create a dedicated, secure HTTPS webhook endpoint.
  • Implement logic to parse incoming JSON payloads (handling strings and integers).
  • Implement strict validation for the X-AUTHENTICATION header.
  • Ensure your server responds specifically with 200 OK within 10 seconds of receipt.
  • Test your endpoint locally using Postman, cURL, or similar API tools.
  • Share your production Webhook URL and X-AUTHENTICATION secret code securely with the ThreatLens integration team.
Last updated on