Webhook Alerts

Pipe Trappr alert payloads into any HTTP endpoint — your SIEM, PagerDuty, Opsgenie, a custom dashboard, or your own incident management system.

Setup

Open Settings → Notifications → Webhooks

Go to Dashboard → Settings → Notifications → Webhooks → Add webhook.

Enter your endpoint URL

Enter the HTTPS URL that Trappr should POST to. The endpoint must return a 2xx status code to acknowledge delivery. Trappr retries up to 3 times on non-2xx responses.

Optionally add a signing secret

Generate a signing secret in the webhook settings. Trappr adds an X-Trappr-Signature header to every delivery so your endpoint can verify the payload came from Trappr and wasn't tampered with.

Send a test delivery

Click Send test payload to send a sample alert to your endpoint and confirm receipt.

Payload format

Trappr delivers alerts as JSON via HTTP POST. The payload structure is consistent across all event types.

JSON

{
  "event":     "canary.triggered",
  "timestamp": "2026-06-18T12:34:56.789Z",
  "severity":  "critical",
  "workspace": "ws_XXXX",
  "app": {
    "id":   "app_XXXX",
    "name": "Customer Support Agent"
  },
  "agent": {
    "id":   "cht_agent_XXXX",
    "name": "support-v3"
  },
  "incident": {
    "id":          "inc_XXXX",
    "type":        "canary_triggered",
    "tokenId":     "tok_XXXX",
    "executionId": "chtx_XXXX",
    "dashboardUrl": "https://app.trappr.net/dashboard/incidents/inc_XXXX"
  }
}

Event types

Event	Triggered when
`canary.triggered`	A canary token was seen outside its boundary
`dlp.match`	Sensitive data detected in a request or response
`agent.tampered`	Agent fingerprint deviated from registered profile
`agent.deactivated`	Agent key revoked after tamper event
`policy.blocked`	Request blocked in ENFORCE mode
`execution.started`	New execution token created
`execution.completed`	Execution marked complete

Verifying the signature

Python

import hmac
import hashlib

def verify_trappr_signature(payload_bytes: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
signature = request.headers.get("X-Trappr-Signature", "")
is_valid  = verify_trappr_signature(request.body, signature, WEBHOOK_SECRET)

Always verify the X-Trappr-Signature header before processing webhook payloads. Reject any payload that fails verification.

← PreviousEmail Alerts Next →Zero-Trust Model