Webhooks

Real-time eventnotifications

PentestForge Webhooks push security events to your systems the moment they happen. No polling. No delays. Integrate into Slack, Microsoft Teams, PagerDuty, Jira, or any HTTP endpoint.

How it works

Step 1

Register endpoint

Add your HTTPS URL and select event types in Settings → Webhooks or via API.

Step 2

Save your secret

PentestForge generates a unique HMAC secret. Store it securely — it’s shown only once.

Step 3

Receive notifications

When an event fires, we POST a JSON payload to your URL with HMAC-SHA256 signature.

Step 4

Verify & process

Validate the X-PentestForge-Signature header, then process the event in your workflow.

Event types

Subscribe to the events that matter to your workflow. Each event delivers a structured JSON payload.

scan.completed

Scan finished successfully

Payload fields: run_id, target, scan_type, findings_count, completed_at

scan.failed

Scan encountered an error

Payload fields: run_id, target, scan_type, completed_at

finding.critical

Critical-severity finding discovered

Payload fields: finding_id, run_id, severity, title, affected_host, cve

report.ready

Report generated and ready for download

Payload fields: run_id, target, scan_type, formats

deepscan.completed

AI Deep Exploitation analysis finished

Payload fields: run_id, target, scan_type, proven_findings_count, false_positives

Payload format & signatures

Every delivery includes a cryptographic signature so you can verify authenticity.

Example payload — scan.completed

json

{
  "event": "scan.completed",
  "timestamp": "2026-05-14T10:35:00Z",
  "run_id": "a1b2c3d4-e5f6-...",
  "target": "example.com",
  "scan_type": "webnetsec",
  "findings_count": 23,
  "completed_at": "2026-05-14T10:41:42Z"
}

Example payload — finding.critical

json

{
  "event": "finding.critical",
  "timestamp": "2026-05-14T10:38:15Z",
  "finding_id": "f7e6d5c4-b3a2-...",
  "run_id": "a1b2c3d4-e5f6-...",
  "severity": "critical",
  "title": "SQL Injection in login endpoint",
  "affected_host": "example.com",
  "cve": "CVE-2026-1234"
}

HTTP headers

http

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-PentestForge-Signature: sha256=<hex_hmac>
X-PentestForge-Event: scan.completed
User-Agent: PentestForge-Webhook/1.0

Verify signature (Python)

python

import hmac, hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Verify signature (Node.js)

javascript

const crypto = require('crypto');

function verifySignature(payload, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Reliability & security

HTTPS-only

All webhook URLs must use HTTPS. Plain HTTP endpoints are rejected at creation time.

HMAC-SHA256 signing

Every payload is signed with a unique secret using HMAC-SHA256. Verify authenticity before processing.

Retry with backoff

Failed deliveries are retried 3 times with exponential backoff (1s, 3s, 9s). 10-second timeout per attempt.

Auto-disable on failure

Webhooks are automatically disabled after 5 consecutive failures to prevent noise. Re-enable any time.

10 per user

Up to 10 webhooks per user. Subscribe each to the specific event types you care about.

Rate-limited test

One test delivery per 30 seconds per webhook to prevent abuse of the test endpoint.

Quick start

bash — Create a webhook

# Create a webhook via API
curl -X POST https://api.pentest-forge.com/api/v2/webhooks/ \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/pentestforge",
    "events": ["scan.completed", "finding.critical", "deepscan.completed"],
    "description": "Slack notification endpoint"
  }'

# Response includes your secret (shown only once!)
# {
#   "id": "...",
#   "secret": "a1b2c3d4...",
#   ...
# }

bash — Test & list

# Send a test payload
curl -X POST https://api.pentest-forge.com/api/v2/webhooks/<id>/test \
  -H "Authorization: Bearer <your-token>"

# List your webhooks
curl https://api.pentest-forge.com/api/v2/webhooks/ \
  -H "Authorization: Bearer <your-token>"

bash — Manage

# Update webhook (disable)
curl -X PATCH https://api.pentest-forge.com/api/v2/webhooks/<id> \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

# Delete webhook
curl -X DELETE https://api.pentest-forge.com/api/v2/webhooks/<id> \
  -H "Authorization: Bearer <your-token>"

Integration examples

Slack

Post critical findings to a #security channel. Alert on-call when a scan fails.

Jira

Auto-create tickets for critical findings with severity, CVE, and affected host.

PagerDuty

Trigger incidents for finding.critical events. Route to the right on-call responder.