View as Markdown

Webhook Documentation

Receive scan results as they finish, instead of polling the API. SIDEX sends an HTTP POST to your endpoint for each event.

Events

Add an endpoint under Settings, Webhooks, and choose which events it receives.

EventSent when
scan.completedA scan finished with results
scan.failedA scan failed for good, after its automatic retries

Headers and Signature

HeaderValue
Content-Typeapplication/json
X-Sidex-EventThe event, scan.completed or scan.failed
X-Sidex-SignatureHex SHA-256 HMAC of the raw request body, keyed with your webhook secret
X-Sidex-Delivery-IdUnique id of this delivery

Compute the signature over the raw body rather than re-serialized JSON, and compare it in constant time. Use the whole secret as the key, including its whsec_ prefix. These examples need only the standard library of each language.

Node.js, node:crypto
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the untouched body, for example from express.raw({ type: "application/json" })
// signatureHeader is req.headers["x-sidex-signature"]
export function isFromSidex(rawBody, signatureHeader, secret) {
  const expected = Buffer.from(createHmac("sha256", secret).update(rawBody).digest("hex"));
  const received = Buffer.from(signatureHeader ?? "");
  return expected.length === received.length && timingSafeEqual(expected, received);
}

Delivery

  • Respond with any 2xx status within 30 seconds. Anything else is recorded as a failed delivery.
  • Each event is sent once. Retry a failed delivery from the Webhook Logs page.

Data by Plan

Payloads follow your plan, like API responses. A dimension your plan does not include is null.

DimensionContainsPlans
securityVerdict, threat score, threat confidences, SSL, brand impersonationAll plans
trustSSL chain, domain WHOIS for the final and original domainAll plans
contentPage title, language, forms, gambling and adult contentStarter, Pro, Enterprise
businessCompany, business type, industryPro, Enterprise
insightAI summary, key findings, risk factors, recommendationsPro, Enterprise
technicalHTTP status, IPs, ASN, network requests, technologiesEnterprise

Payloads

data has the same shape as a scan from the API, so the same parsing code handles both.

scan.completed, Enterprise plan
{
  "event": "scan.completed",
  "data": {
    "id": "65a1f0c2b3d4e5f6a7b8c9d0",
    "url": "https://www.example.com/",
    "domain": "example.com",
    "originalUrl": "https://example.com",
    "originalDomain": "example.com",
    "status": "completed",
    "scanType": "deep",
    "timeout": false,
    "redirectChain": [
      "https://example.com",
      "https://www.example.com/"
    ],
    "hasScreenshot": true,
    "redirectHops": [
      {
        "url": "https://example.com",
        "domain": "example.com",
        "status": 301,
        "via": "start",
        "ip": "93.184.216.34",
        "country": "United States of America",
        "asnOrg": "Edgecast Inc."
      },
      {
        "url": "https://www.example.com/",
        "domain": "example.com",
        "status": 200,
        "via": "redirect",
        "ip": "93.184.216.34",
        "country": "United States of America",
        "asnOrg": "Edgecast Inc."
      }
    ],
    "security": {
      "treatLevel": "safe",
      "threatScore": 0.05,
      "threats": {
        "phishing": 0,
        "malware": 0,
        "scam": 0,
        "deceptiveContent": 0,
        "adult": 0,
        "gambling": 0
      },
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt",
        "issueDate": "2026-09-01T00:00:00.000Z",
        "expireDate": "2026-11-30T00:00:00.000Z",
        "ageInDays": 62
      },
      "brandImpersonation": {
        "detected": false,
        "brand": null,
        "confidence": 0
      },
      "riskFactors": [],
      "suspiciousKeywords": []
    },
    "business": {
      "category": "technology",
      "companyName": "Example Inc.",
      "companyDomain": "example.com",
      "companyCountry": "US",
      "businessType": "technology",
      "industryClassification": "Software"
    },
    "technical": {
      "httpStatusCode": 200,
      "contentType": "text/html; charset=UTF-8",
      "ipAddresses": [
        "93.184.216.34"
      ],
      "cspHeaders": [],
      "ipCountry": "US",
      "ipCountryName": "United States of America",
      "asn": "15133",
      "asnOrg": "Edgecast Inc.",
      "network": {
        "requests": 12,
        "httpsRequests": 12,
        "ips": [
          {
            "ip": "93.184.216.34",
            "requests": 12,
            "redirects": 1,
            "country": "US",
            "countryName": "United States of America",
            "region": "California",
            "city": "Los Angeles",
            "asn": "15133",
            "asnOrg": "Edgecast Inc."
          }
        ],
        "hosts": [
          {
            "host": "www.example.com",
            "parent": null,
            "requests": 12
          }
        ],
        "redirects": []
      },
      "technologies": [
        {
          "name": "Nginx",
          "category": "Web server",
          "version": null
        }
      ]
    },
    "content": {
      "pageTitle": "Example Domain",
      "metaDescription": "This domain is for use in documentation examples.",
      "language": "en",
      "forms": {
        "hasLoginForm": false,
        "requestsPersonalInfo": false,
        "requestedInfoTypes": []
      },
      "gambling": {
        "related": false,
        "type": [],
        "confidence": 0
      },
      "adult": {
        "related": false,
        "type": [],
        "confidence": 0
      },
      "suspiciousExternalDomains": []
    },
    "trust": {
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt",
        "intermediateCas": [
          "R13 (Let's Encrypt)"
        ],
        "rootCa": "ISRG Root X1 (Internet Security Research Group)",
        "issueDate": "2026-09-01T00:00:00.000Z",
        "expireDate": "2026-11-30T00:00:00.000Z",
        "ageInDays": 62
      },
      "domain": {
        "registeredAt": "1995-08-14T00:00:00.000Z",
        "expireDate": "2027-08-13T00:00:00.000Z",
        "ageInDays": 11404,
        "registrar": "RESERVED-Internet Assigned Numbers Authority",
        "registrantCountry": null,
        "status": [
          "client transfer prohibited"
        ],
        "nameservers": [
          "a.iana-servers.net",
          "b.iana-servers.net"
        ],
        "abuseEmail": null
      },
      "originalDomain": {
        "registeredAt": "1995-08-14T00:00:00.000Z",
        "expireDate": "2027-08-13T00:00:00.000Z",
        "ageInDays": 11404,
        "registrar": "RESERVED-Internet Assigned Numbers Authority",
        "registrantCountry": null,
        "status": [
          "client transfer prohibited"
        ],
        "nameservers": [
          "a.iana-servers.net",
          "b.iana-servers.net"
        ],
        "abuseEmail": null
      }
    },
    "insight": {
      "summary": "Reserved documentation domain with no malicious content.",
      "keyFindings": [
        "Domain is reserved for documentation"
      ],
      "riskFactors": [],
      "positiveIndicators": [
        "Valid SSL certificate",
        "Domain older than 5 years"
      ],
      "recommendations": [
        "No action needed"
      ]
    },
    "errorMessage": null,
    "retryCount": 0,
    "createdAt": "2026-11-02T03:48:52.023Z",
    "updatedAt": "2026-11-02T03:49:05.673Z",
    "startedAt": "2026-11-02T03:48:54.519Z",
    "completedAt": "2026-11-02T03:49:05.673Z"
  }
}
scan.completed, Free plan
{
  "event": "scan.completed",
  "data": {
    "id": "65a1f0c2b3d4e5f6a7b8c9d0",
    "url": "https://www.example.com/",
    "domain": "example.com",
    "originalUrl": "https://example.com",
    "originalDomain": "example.com",
    "status": "completed",
    "scanType": "deep",
    "timeout": false,
    "redirectChain": [
      "https://example.com",
      "https://www.example.com/"
    ],
    "hasScreenshot": true,
    "redirectHops": [
      {
        "url": "https://example.com",
        "domain": "example.com",
        "status": 301,
        "via": "start",
        "ip": "93.184.216.34",
        "country": "United States of America",
        "asnOrg": "Edgecast Inc."
      },
      {
        "url": "https://www.example.com/",
        "domain": "example.com",
        "status": 200,
        "via": "redirect",
        "ip": "93.184.216.34",
        "country": "United States of America",
        "asnOrg": "Edgecast Inc."
      }
    ],
    "security": {
      "treatLevel": "safe",
      "threatScore": 0.05,
      "threats": {
        "phishing": 0,
        "malware": 0,
        "scam": 0,
        "deceptiveContent": 0,
        "adult": 0,
        "gambling": 0
      },
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt",
        "issueDate": "2026-09-01T00:00:00.000Z",
        "expireDate": "2026-11-30T00:00:00.000Z",
        "ageInDays": 62
      },
      "brandImpersonation": {
        "detected": false,
        "brand": null,
        "confidence": 0
      },
      "riskFactors": [],
      "suspiciousKeywords": []
    },
    "business": null,
    "technical": null,
    "content": null,
    "trust": {
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt",
        "intermediateCas": [
          "R13 (Let's Encrypt)"
        ],
        "rootCa": "ISRG Root X1 (Internet Security Research Group)",
        "issueDate": "2026-09-01T00:00:00.000Z",
        "expireDate": "2026-11-30T00:00:00.000Z",
        "ageInDays": 62
      },
      "domain": {
        "registeredAt": "1995-08-14T00:00:00.000Z",
        "expireDate": "2027-08-13T00:00:00.000Z",
        "ageInDays": 11404,
        "registrar": "RESERVED-Internet Assigned Numbers Authority",
        "registrantCountry": null,
        "status": [
          "client transfer prohibited"
        ],
        "nameservers": [
          "a.iana-servers.net",
          "b.iana-servers.net"
        ],
        "abuseEmail": null
      },
      "originalDomain": {
        "registeredAt": "1995-08-14T00:00:00.000Z",
        "expireDate": "2027-08-13T00:00:00.000Z",
        "ageInDays": 11404,
        "registrar": "RESERVED-Internet Assigned Numbers Authority",
        "registrantCountry": null,
        "status": [
          "client transfer prohibited"
        ],
        "nameservers": [
          "a.iana-servers.net",
          "b.iana-servers.net"
        ],
        "abuseEmail": null
      }
    },
    "insight": null,
    "errorMessage": null,
    "retryCount": 0,
    "createdAt": "2026-11-02T03:48:52.023Z",
    "updatedAt": "2026-11-02T03:49:05.673Z",
    "startedAt": "2026-11-02T03:48:54.519Z",
    "completedAt": "2026-11-02T03:49:05.673Z"
  }
}
scan.failed, shortened
{
  "event": "scan.failed",
  "data": {
    "id": "65a1f0c2b3d4e5f6a7b8c9d0",
    "url": "https://unreachable.example.com",
    "domain": "unreachable.example.com",
    "status": "failed",
    "scanType": "deep",
    "errorMessage": "We could not reach this site. Please check the URL and try again.",
    "retryCount": 4
  }
}

Best Practices

  1. Verify X-Sidex-Signature before trusting a request.
  2. Check dimensions for null before reading them.
  3. Handle repeats safely, using data.id and X-Sidex-Delivery-Id. A manual retry sends the event again.
  4. Store the payload and respond right away, then process it in the background.