Webhooks & Push Notifications

Webhooks deliver events such as auto-protection changes, failban actions and rule matches to your own endpoint as JSON. Every payload is signed with HMAC-SHA256.

Creating a webhook

1. Go to Console → WAF → [your domain] → API Keys and open the Webhooks section.

2. Click the new-webhook button and fill in the form:

   • Name — 3–8 alphanumeric characters
   • URL — your http:// or https:// endpoint (credentials embedded in the URL are not allowed)
   • Event type — challenge, failban or rule
   • Throttle window — between 1 minute and 24 hours
   • (Optional) Basic Auth username and password

3. Save, then use the Test button to send a sample payload to your endpoint.

Verify every incoming request with the X-HEIMWALL-Signature header: compute the HMAC-SHA256 of the raw request body with your webhook secret and compare it to the hex value in the header. If they match, the payload came from HEIMWALL and has not been tampered with.

X-HEIMWALL-Signature: <hex-encoded HMAC-SHA256 of raw request body>

Throttling

At most 1 event per event type is delivered per throttle window. Pick a window that keeps your endpoint from being flooded during a heavy attack.

Event types and payload formats

challenge — auto-protection activated/deactivated

Fires when an automatic or manual challenge is enabled or disabled:

{
  "auto_challenge": "on",
  "challenge_type": "js",
  "activation": "2026-10-20T14:32:05Z"
}

• auto_challenge: on | off
• challenge_type: js | captcha
• activation: RFC3339 timestamp

failban — IP banned/unbanned

Fires when an IP is added to or removed from the failban cache:

{
  "is": "add",
  "ip": "203.0.113.42",
  "expire": "2026-10-20T15:02:05Z",
  "adding": "2026-10-20T14:52:05Z"
}

• is: add | delete
• ip: the banned IP
• expire: when the ban ends (RFC3339)
• adding: when the ban was applied (RFC3339)

rule — a rule with the webhook action matched

Fires when a rule containing the webhook action matches a request:

{
  "rule": "admin-protect",
  "timestamp": "2026-10-20T14:32:05Z",
  "ray": "7f3a9c2e1b4d",
  "ip": "203.0.113.42",
  "host": "example.com",
  "request": "GET /wp-admin HTTP/2",
  "status": 403,
  "bytes": 1024,
  "duration": 12,
  "tls": "TLS 1.3",
  "referer": "",
  "useragent": "Mozilla/5.0 ...",
  "backend": "default",
  "server": "edge-ist-1"
}

To add a webhook trigger to any rule: define your conditions on Console → WAF → [your domain] → Rules → New Rule and tick webhook as an action.

Package scope

Webhook delivery is a package-gated feature. If the section appears locked, your package does not include it.

Mobile push notifications

Install the HEIMWALL mobile app (iOS and Android) and sign in with your account: your device registers automatically and starts receiving push notifications — so you hear about an attack or a server failure without checking the console.

Manage registered devices under Settings → Profile → Devices: you can remove a device (it stops receiving push) or send it a test notification.

Events that trigger a push:

• Origin health — origin unreachable / back online
• Maintenance mode — enabled / disabled
• Deployment (ZDD) — started / succeeded / failed / incomplete
• Security — new IP ban (failban), auto-protection engaged / lifted, protection mode changed, waiting room active, traffic spike
• SSL — certificate expiring / auto-renewal failed
• Quota — bandwidth usage at 80% warning / cap reached, domain traffic alert and cutoff notifications

Push can be toggled per event type. The email channel is independent of push — you can additionally enable email notifications for the same events.