Callbacks

Packetly provides a callback mechanism to notify your application when a file scan is completed. This documentation outlines the callback system's functionality, requirements, and implementation details. Endpoints that employ callbacks will have a signing signature generated at creation time. Just so you know – the signing signature can be regenerated at anytime if you wish to rotate credentials.

Callback Requirements

• Protocol: HTTPS/HTTP only
• Method: POST
• Content-Type: application/json
• Recommended Setting: ASYNC enabled for the Endpoint.

Callback Configuration

When setting up the callback URL, ensure:

1. The endpoint is publicly accessible
2. HTTPS is correctly configured with valid SSL certificates
3. Your server can handle POST requests
4. The endpoint can process JSON payloads

Request Payload

The callback will send a JSON payload with the following structure:

{
  "ip": "string", // Client IP address
  "file_id": "string", // Unique identifier for the file
  "path": "string", // Request path
  "etag": "string", // MD5 hash
  "sha256": "string", // SHA256 hash of the file
  "access_key": "string", // X-Access-Key header value
  "timestamp": "Y-m-d H:i:s", // UTC timestamp
  "size": "number", // File size in bytes
  "host": "string",// Request host
  "user_agent": "string",// User agent or "Unknown"
  "scan_types": [], // Array of requested scan types
  "callback_url": "string", // X-Callback-Url header value
  "mime_type": "string", // Detected MIME type
  "nsfw_threshold": "number|null", // NSFW detection threshold
  "billing": "number", // Billable units of the scan
  "results": {
      "clamav": {
          "process_time": "number",
          "virus": boolean,
          "stats": "string", // Type of malware or virus detected
          "scan_time": "number",
       },
       "nsfw": {
          "stats": [
            {"className": "Sexy", "probability": "float"},
            {"className": "Porn", "probability": "float"}, 
            {"className": "Neutral", "probability": "float"},
            {"className": "Hentai", "probability": "float"},
            {"className": "Drawing", "probability": "float"}]
       }
  }
}

Retry Mechanism

If the callback request fails, Packetly implements the following retry logic:

• Maximum of 3 attempts per callback
• After 3 failed attempts, the failure is logged in the Packetly system

Response Requirements

• Return HTTP 200 for successful processing
• Return HTTP 4xx for client errors
• Return HTTP 5xx for server errors

Validating Authenticity

To ensure the authenticity of callbacks from Packetly, you should validate the signature included with each request. Every callback request includes two important security headers:

• X-Packetly-Signature : A signature generated using your signing secret
• X-Packetly-Timestamp : The Unix timestamp when the request was generated

To validate a callback:

1. Concatenate the timestamp and raw request payload
2. Generate an HMAC signature using SHA-256 and your signing secret provided via the Packetly dashboard for the respective Endpoint.
3. Compare this signature with the one provided in the X-Packetly-Signature header

Examples are provided below:

PHP

private function callbackRequestIsValid(
    string $payload, 
    string $signature, 
    int $timestamp, 
    string $secret): bool
{
    $expectedSignature = hash_hmac(
        'sha256',
        $timestamp . $payload,
        $secret
    );
    return hash_equals($expectedSignature, $signature);
}

Javascript

function isCallbackRequestValid(payload, signature, timestamp, secret) {
    const crypto = require('crypto');
    
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(timestamp + payload)
        .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(expectedSignature),
        Buffer.from(signature)
    );
}

Python

import hmac
import hashlib

def is_callback_request_valid(payload: str, signature: str, 
                            timestamp: int, secret: str) -> bool:
    expected_signature = hmac.new(
        secret.encode(),
        f"{timestamp}{payload}".encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_signature, signature)

To prevent timing attacks, always use a timing-safe string comparison (like hash_equals() in PHP) when comparing signatures. Never use standard string comparison operators.

Your signing secret is in your Packetly dashboard. Keep it secure and never expose it in client-side code or public repositories.