Developer portal
Webhooks
Reliable, signed event delivery for SIEM, SOAR, and ticketing automation.
Last updated: 2026-06-09
Event model
Qtangl webhooks are push events emitted as integration state changes and scans complete. The canonical payload format is qtangl-webhook-v2, which is designed for ingestion into Splunk, Datadog, Elastic, and internal event buses without custom translators.
Payload fields (SIEM v2)
| Field | Type | Required | Description |
|---|---|---|---|
| schemaVersion | string | Yes | Payload schema identifier. Current value: qtangl-webhook-v2. |
| event | string | Yes | Event name, such as scan.complete. |
| tenantId | string | Yes | Tenant identifier for multi-tenant routing in downstream systems. |
| scanId | string | Yes | Scan job id associated with the event. |
| readinessScore | number | No | Composite score from 0 to 100 when available for this event. |
| alerts[] | array | No | Triggered alert summaries to help SIEM correlation and prioritization. |
| verifyUrl | string | No | Canonical verification URL for report provenance checks. |
| message | string | No | Human-readable summary string intended for operator notifications. |
HMAC signing and verification
Configure a per-endpoint signing secret to receive authenticity headers on every delivery. Your receiver should compute HMAC SHA-256 from the raw request body and compare againstX-Qtangl-Signature using constant-time comparison.
| Field | Type | Required | Description |
|---|---|---|---|
| X-Qtangl-Timestamp | unix-seconds | Yes | Server-side event timestamp used in signature input and replay windows. |
| X-Qtangl-Signature | sha256=<hex> | Yes | HMAC SHA-256 signature over `${timestamp}.${rawBody}` using your webhook secret. |
| X-Qtangl-Delivery-Id | uuid | Yes | Unique delivery id for deduplication and delivery traceability. |
expected = hmac_sha256(secret, "${timestamp}.${rawBody}")
if !constant_time_equal("sha256=" + expected, header_signature):
reject 401Delivery retries, DLQ, and replay
- Retries use exponential backoff for transient 5xx and network timeout failures.
- Permanent failures are moved to the webhook dead-letter queue (DLQ) with full delivery metadata.
- Operators can replay selected DLQ events after receiver fixes without rerunning source scans.
- Replay preserves original payload and issues a new delivery id for auditability.
Receiver hardening checklist
- Accept only HTTPS and enforce modern TLS policy at your edge.
- Validate timestamp skew and reject messages outside your tolerance window.
- Deduplicate on delivery id to make handler execution idempotent.
- Log request id, delivery id, and status for incident reconstruction.
For concrete field examples, see SIEM webhook v2 field dictionary.
Found an issue? Report documentation feedback