BlucaScan Documentation

Webhook Configuration

Set up real-time notifications for file scan results and transfer status updates. Configure webhook endpoints and security settings to receive instant updates.

Webhook Configuration
Environment variables for webhook setup
# Webhook Configuration
BLUCA_SCAN_WEBHOOK_ENABLED=true
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_URL=https://HOST/PATH
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_METHOD=POST
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_MAX_RETRIES=3
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_RETRY_DELAY_IN_MILLIS=10000

# Webhook Authentication
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_AUTH_ENABLED=true

# Basic Authentication Configuration
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_USERNAME=username
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_PASSWORD=password

# API Key Configuration
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY=api-key
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY_HEADER_NAME=X-BlucaScan-Event-Endpoint-ApiKey
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY_REQUEST_BODY_FIELD_NAME=fieldName

# Webhook HMAC Signature Configuration
BLUCA_SCAN_WEBHOOK_EVENT_HMAC_HEADER_NAME=X-BlucaScan-Event-Signature
BLUCA_SCAN_WEBHOOK_EVENT_HMAC_ALGORITHM=HMAC_SHA256

BLUCA_SCAN_WEBHOOK_EVENT_VALIDATION_ENABLED=true

Basic Configuration

Enable webhooks and set endpoint URL

Required

Authentication

Configure API keys and basic auth

Recommended

Security

HMAC signature validation

Essential
Webhook Events
scan.completed

Sent when file scanning is complete

transfer.completed

Sent when file transfer is finished

scan.malicious

Sent when malicious content is detected

transfer.failed

Sent when file transfer fails

Security Features
HMAC Signatures

Webhook payloads signed with your secret

Timestamp Verification

Prevent replay attacks with timestamps

HTTPS Only

All webhooks sent over secure connections

Retry Logic

Automatic retries for failed deliveries

Webhook Payload Examples
Sample webhook payloads for different events

scan.completed
Clean File Notification

{
  "event": "scan.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "fileIdentifier": "fec850b7-7cbb-4ff2-8ff9-23e6489f46c2",
  "data": {
    "fileScanResult": {
      "status": "CLEAN",
      "fileName": "document.pdf",
      "fileSize": 245760,
      "timeTakenInMillis": 120
    },
    "fileTransferStatus": "SUCCEEDED"
  }
}

scan.malicious
Malicious File Alert

{
  "event": "scan.malicious",
  "timestamp": "2024-01-15T10:35:00Z",
  "fileIdentifier": "abc123d4-5678-9012-3456-789012345678",
  "data": {
    "fileScanResult": {
      "status": "MALICIOUS",
      "fileName": "suspicious.exe",
      "fileSize": 1024000,
      "foundViruses": {
        "stream": ["Trojan.Generic", "Malware.Detected"]
      },
      "timeTakenInMillis": 85
    },
    "fileTransferStatus": "SKIPPED"
  }
}
Webhook Security Implementation
How to verify webhook authenticity in your application

Signature Verification

Each webhook includes an HMAC-SHA256 signature in the headers:

x-blucascan-signature: a1b2c3d4e5f6...
x-blucascan-timestamp: 1642248600

Verification Example (Node.js)

require("dotenv").config();
const express = require("express");
const crypto = require("crypto");

const app = express();

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || "your-webhook-secret-key";

app.use(
  express.json({
    verify: (req, res, buf) => {
      // Store the raw body for HMAC verification
      req.rawBody = buf;
    },
  })
);

// HMAC SHA256 authentication middleware
const verifyHmacSignature = (req, res, next) => {
  const signature =
    req.headers["x-blucascan-signature"] || req.headers["your-custom-header"];

  if (!signature) {
    return res.status(401).json({ error: "Missing signature header" });
  }

  // Extract the signature value (remove 'sha256=' prefix if present)
  const signatureValue = signature.replace("sha256=", "");

  // Calculate expected signature
  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest("base64");

  // Compare signatures
  try {
    if (
      !crypto.timingSafeEqual(
        Buffer.from(signatureValue, "base64"),
        Buffer.from(expectedSignature, "base64")
      )
    ) {
      return res.status(401).json({ error: "Invalid signature" });
    }
  } catch (error) {
    return res.status(401).json({ error: "Invalid signature format" });
  }

  next();
};
  
// Webhook endpoint with HMAC authentication
app.post("/webhook", verifyHmacSignature, (req, res) => {
  try {
    // Process the webhook data here
    // This is where you would add your business logic
    const { event, data } = req.body;

    switch (event) {
      case "scan.completed":
        // Handle scan completion
        break;
      case "transfer.completed":
        // Handle transfer completion
        break;
      default:
      // Handle unknown events
    }

    res.status(200).json({ success: true, message: "Webhook processed successfully" });
  } catch (error) {
    console.error("Error processing webhook:", error);

    res.status(500).json({
      success: false,
      error: "Internal server error",
    });
  }
});

app.listen(PORT, () => {
  console.log("Webhook server running on port 3000");
});
}
Configuration Examples
Common webhook configuration scenarios

Basic Webhook Setup

# Enable Webhook Notifications
BLUCA_SCAN_WEBHOOK_ENABLED=true

# Webhook Endpoint Configuration
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_URL=https://HOST/PATH
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_METHOD=POST
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_MAX_RETRIES=3
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_RETRY_DELAY_IN_MILLIS=10000

# Basic Authentication Configuration
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_USERNAME=username
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_PASSWORD=password

Webhooks Disabled

# Disable Webhook Notifications
BLUCA_SCAN_WEBHOOK_ENABLED=false

When url is null, no webhook notifications will be sent