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.
Scheduled briefing delivery
In the command center, open Advanced → Push everywhere. Select channels, enter explicit email recipients, choose an interval from 1 to 168 hours, enable scheduled delivery, and save preferences. Older preferences require saving again before scheduling starts. Saving requires persistent storage; enabling delivery also requires a healthy scheduler. Send briefing now sends the current form once without saving its settings.
In Settings → Integrations, subscribe Slack destinations to briefing.slack, Teams destinations to briefing.teams, and generic webhook destinations to briefing.webhook. Email delivery uses the explicitly listed recipients, rather than a webhook subscription.
Review the first scheduled time and last recorded outcome in the panel. Partial and failed outcomes are not successful delivery to every destination. An uncertain attempt is not automatically replayed, because a destination may already have accepted it. Use the webhook payload's deliveryIdto deduplicate at the receiver; transport retries do not guarantee exactly-once delivery.
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