Secure Webhook (JWT/JWKS)
AI-generatedOverview
This node implements a secure webhook with multiple authentication and protection profiles, including HMAC, JWT (JWKS), API Key, and a combo mode that adds IP allow/deny lists. It is designed to protect webhook endpoints by verifying request authenticity, preventing replay attacks, enforcing rate limits, and optionally exporting audit metadata. Common use cases include securing public webhooks, integrating with enterprise identity providers (Auth0, Okta, OIDC), and protecting partner integrations with IP restrictions.
Use Case Examples
- A company uses the JWT (JWKS) profile to verify incoming webhook requests from their identity provider, ensuring only authorized tokens are accepted.
- A developer configures the HMAC profile with timestamp and nonce headers to prevent replay attacks on a public webhook endpoint.
- An organization uses the combo profile to enforce HMAC signatures and restrict access to specific IP ranges for partner VPNs.
Properties
| Name | Meaning |
|---|---|
| Security Profile | Selects the authentication and protection method for the webhook, such as HMAC, JWT (JWKS), API Key, or Combo (HMAC + IP allowlist). |
| Webhook Path | Unique path segment(s) for the webhook URL, must be unique across active workflows. |
| Trusted Proxy Hops | Number of trusted proxies in front of n8n to correctly extract client IP from X-Forwarded-For header. |
| Max Body (bytes) | Maximum allowed raw request body size in bytes; requests exceeding this are rejected. |
| Allowed Content-Types | Comma-separated list of allowed content types; requests must have one of these content types. |
| Rate Limit / Minute (per IP) | Maximum number of requests allowed per IP address per minute; exceeding results in 429 error. |
| Timestamp Header | Header name containing UNIX timestamp in seconds, used with nonce for replay protection. |
| Nonce Header | Header name containing a one-time unpredictable value per request for replay defense. |
| Max Skew (seconds) | Allowed clock skew between client and server timestamps to balance replay defense and false positives. |
| HMAC Signature Header | Header name for the HMAC signature, including algorithm prefix; used in HMAC and Combo profiles. |
| HMAC Algorithm | Hash algorithm used for HMAC signature; client and server must match. |
| IP Allow (CIDR, comma-separated) | List of allowed IP networks in CIDR notation; checked after deny list; used in Combo profile. |
| IP Deny (CIDR, comma-separated) | List of denied IP networks in CIDR notation; deny applies before allow; used in Combo profile. |
| Require Additional Static Header | Enforces presence of a static header with a specific value in addition to HMAC for defense-in-depth. |
| Static Header Name | Name of the static header required alongside HMAC. |
| Static Header Value | Expected value of the static header; can be plaintext or secret. |
| JWT: Expected Issuer (optional) | Expected 'iss' claim value in JWT; empty allows any issuer (not recommended). |
| JWT: Audience (optional) | Expected 'aud' claim value in JWT; empty allows any audience (not recommended). |
| Signature Mode | Determines what parts of the request are signed in HMAC mode: body only or extended (method, path, query, timestamp, nonce, body hash). |
| Dual-Key Rotation: Previous Secret | Optional previous secret key accepted during a key rotation window. |
| Dual-Key Window (minutes) | Time window during which the previous secret is accepted for key rotation. |
| Enable Redis (Replay & Rate) | Enables Redis backend for replay protection and rate limiting, recommended for high availability and clustering. |
| Redis URL | Connection URL for Redis server; used if Redis is enabled. |
| Redis Namespace | Namespace prefix for Redis keys to avoid collisions. |
| JWKS Cooldown (ms) | Minimum interval between JWKS fetches to reduce network load and handle key rotation. |
| JWKS Fetch Timeout (ms) | Timeout duration for retrieving JWKS keys; too short may cause false failures. |
| Require mTLS (check proxy headers) | Requires upstream proxy to confirm successful mutual TLS authentication via headers. |
| mTLS Verify Header | Header name set by proxy on successful mTLS; default is 'x-ssl-client-verify' with value 'SUCCESS'. |
| mTLS Subject Header (optional) | Header containing the Distinguished Name of the client certificate; can be restricted by regex. |
| Subject Allow Regex (optional) | Regex pattern that the client certificate DN must match; failure to match denies access. |
| Audit Export | Controls export of metadata about webhook events to an HTTPS endpoint for auditing. |
| Audit Endpoint URL | URL of the HTTPS endpoint to receive audit event metadata; used if audit export is enabled. |
| Audit Bearer Token (optional) | Optional bearer token sent as Authorization header to the audit endpoint. |
Output
JSON
event- Metadata about the webhook event such as accept/reject status and reason.payload- The actual webhook payload data received (not exported in audit mode).
Dependencies
- An API key credential for JWT JWKS profile authentication
- Optional Redis server for replay protection and rate limiting
Troubleshooting
- 413 error indicates request body size exceeds configured Max Body limit; increase limit or reduce payload size.
- 415 error means the Content-Type header is missing or not in the allowed list; ensure correct Content-Type is sent.
- 429 error occurs when rate limit per IP is exceeded; adjust rateMax or implement backoff.
- JWT verification failures may occur if issuer or audience claims do not match configured values; verify JWT claims and JWKS URL.
- Replay protection may cause false positives if client and server clocks are not synchronized within Max Skew.
- If using Redis, connection issues may cause fallback to in-memory storage, affecting cluster safety and persistence.