Webhooks
Pentestas pushes JSON events to any HTTPS URL you configure. Good for:
- Alerting a SIEM on CRITICAL findings.
- Kicking a GitHub Action on scan completion.
- Pushing findings into Jira / ServiceNow.
- Custom dashboards.
Configure
Settings → Webhooks → New.
- URL — must be HTTPS (HTTP refused at validation time).
- Events — pick one or more subscriptions.
- Secret — opaque string used to HMAC-sign every delivery.
- Description — freeform, for your own audit.
Save — Pentestas sends a test webhook.test event to confirm the URL is live.
Events
| Event | Payload shape |
|---|---|
scan.created |
{event, scan_id, tenant_id, target_url, created_at} |
scan.started |
{event, scan_id, started_at} |
scan.progress |
{event, scan_id, phase, message} (throttled, not per-event) |
scan.completed |
{event, scan_id, findings_count, severity_breakdown, target_url, timestamp} |
scan.failed |
{event, scan_id, error} |
finding.created |
{event, finding: {...full schema}} |
finding.status_changed |
{event, finding_id, from, to, changed_by} |
agent.connected |
{event, agent_id, hostname} |
agent.disconnected |
{event, agent_id, reason} |
Signing
Every request carries an X-Pentestas-Signature header:
X-Pentestas-Signature: sha256=<hex>
Where <hex> is HMAC-SHA256(secret, raw_body). Verify in your handler before trusting anything.
Python:
import hmac, hashlib
def verify(secret, sig_header, body_bytes):
expected = hmac.new(secret.encode(), body_bytes,
hashlib.sha256).hexdigest()
provided = sig_header.split("=", 1)[1]
return hmac.compare_digest(expected, provided)
Retries
If your endpoint returns 5xx or times out (>10s), Pentestas retries with exponential backoff:
- 30s, 2min, 10min, 1h, 6h, 24h.
After 6 failed attempts, the delivery is moved to the dead-letter queue and an in-app notification fires. The webhook itself isn't disabled — future events still fire. Dead-letter deliveries can be replayed manually.
Successful responses: anything 2xx. Anything else (including 3xx redirects) is treated as failure.
Rate limits
- 50 events / minute per webhook URL.
- If you exceed this, Pentestas buffers up to 10,000 events; beyond that, oldest events are dropped.
Debugging
Settings → Webhooks → click a webhook → Delivery log. Shows the last 100 deliveries with request / response / latency. Click any to see the full JSON body and headers, or to replay.
See also
- Slack — if you just want alerts without writing code
- Findings API — fetch finding details from a webhook handler