Webhook Reference
Generic Format
POST JSON body with these top-level fields:
{
"title": "Xid 79 on node-3",
"text": "deterministic finding",
"severity": "critical",
"details": { /* arbitrary JSON */ },
"tags": ["xid-79", "gpu"],
"source": "denpex-control-plane",
"tenant": "acme",
"dedup_key": "xid-79-node-3-1700000000"
}Per-Destination Adapters
See agents/denpex-platform/src/observability.rs for the exact payload shapes.
| Destination | Field mapping |
|---|---|
| Teams | MessageCard with themeColor, title, text |
| PagerDuty | event_action=trigger, payload.summary, payload.severity |
| Opsgenie | message, priority (P1-P4), source, tags |
| ServiceNow | short_description, urgency, impact, assignment_group |
| Jira | fields.project.key, fields.summary, fields.priority |
| Custom | Raw JSON body with X-Denpex-Signature: sha256=<hmac> header |
Auth
| Destination | Header |
|---|---|
| Teams | (none; URL-embedded secret) |
| PagerDuty | Authorization: Token token=<routing-key> |
| Opsgenie | Authorization: GenieKey <key> |
| ServiceNow | Authorization: Basic <base64(user:pass)> |
| Jira | Authorization: Basic <base64(email:api_token)> |
| Custom | X-Denpex-Signature: sha256=<hex> (HMAC-SHA-256) |
HMAC Verification
When a custom webhook is configured with hmac_secret:
- Compute HMAC-SHA-256 of the raw body using the shared secret.
- Hex-encode.
- Send as
X-Denpex-Signature: sha256=<hex>.
The receiver verifies by:
- Reading the raw body.
- Computing the same HMAC.
- Comparing constant-time.
Reference implementation in agents/denpex-platform/src/observability.rs::hmac_sha256_hex.
Retries
Failed deliveries are retried up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s). On the final failure the audit log records delivery_failed with a hash chain entry.
Throttling
Per-destination rate limit:
| Destination | Default |
|---|---|
| PagerDuty | 30 msg/sec |
| Opsgenie | 50 msg/sec |
| Jira | 5 msg/sec |
| Custom | configurable |
Exceeding the rate limit causes a 1-second sleep; the audit log records delivery_throttled.