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.
| Event | Sent when |
|---|---|
scan.completed | A scan finished with results |
scan.failed | A scan failed for good, after its automatic retries |
Headers and Signature
| Header | Value |
|---|---|
Content-Type | application/json |
X-Sidex-Event | The event, scan.completed or scan.failed |
X-Sidex-Signature | Hex SHA-256 HMAC of the raw request body, keyed with your webhook secret |
X-Sidex-Delivery-Id | Unique 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);
}Bun, Bun.CryptoHasher
import { timingSafeEqual } from "node:crypto";
// rawBody is await request.text(), read before any JSON parsing
// signatureHeader is request.headers.get("X-Sidex-Signature")
export function isFromSidex(rawBody, signatureHeader, secret) {
const expected = Buffer.from(new Bun.CryptoHasher("sha256", secret).update(rawBody).digest("hex"));
const received = Buffer.from(signatureHeader ?? "");
return expected.length === received.length && timingSafeEqual(expected, received);
}Go, crypto/hmac
package webhook
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
)
// rawBody is the result of io.ReadAll(r.Body), read before any JSON parsing.
// signature is r.Header.Get("X-Sidex-Signature").
func IsFromSidex(rawBody []byte, signature, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signature))
}Java 17 or newer, javax.crypto
import static java.nio.charset.StandardCharsets.UTF_8;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public final class SidexWebhook {
// rawBody is request.getInputStream().readAllBytes(), read before any JSON parsing
// signatureHeader is request.getHeader("X-Sidex-Signature")
public static boolean isFromSidex(byte[] rawBody, String signatureHeader, String secret)
throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(UTF_8), "HmacSHA256"));
byte[] expected = HexFormat.of().formatHex(mac.doFinal(rawBody)).getBytes(UTF_8);
byte[] received = (signatureHeader == null ? "" : signatureHeader).getBytes(UTF_8);
return MessageDigest.isEqual(expected, received);
}
}PHP, hash_hmac
<?php
// $rawBody is file_get_contents("php://input"), read before any JSON parsing
// $signature is $_SERVER["HTTP_X_SIDEX_SIGNATURE"] ?? ""
function isFromSidex(string $rawBody, string $signature, string $secret): bool
{
$expected = hash_hmac("sha256", $rawBody, $secret);
return hash_equals($expected, $signature);
}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.
| Dimension | Contains | Plans |
|---|---|---|
security | Verdict, threat score, threat confidences, SSL, brand impersonation | All plans |
trust | SSL chain, domain WHOIS for the final and original domain | All plans |
content | Page title, language, forms, gambling and adult content | Starter, Pro, Enterprise |
business | Company, business type, industry | Pro, Enterprise |
insight | AI summary, key findings, risk factors, recommendations | Pro, Enterprise |
technical | HTTP status, IPs, ASN, network requests, technologies | Enterprise |
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
- Verify
X-Sidex-Signaturebefore trusting a request. - Check dimensions for
nullbefore reading them. - Handle repeats safely, using
data.idandX-Sidex-Delivery-Id. A manual retry sends the event again. - Store the payload and respond right away, then process it in the background.