Secure Webhook (API Key) icon

Secure Webhook (API Key)

Secure webhook trigger with HMAC/JWT auth, replay protection, IP filtering, and per-IP rate limiting. Defaults are safe for public endpoints.

Secure Webhook (API Key)

AI-generated

Overview

This node implements a secure webhook with multiple authentication profiles including HMAC, JWT (JWKS), API Key, and a combo mode that combines HMAC with IP allow/deny lists. It is designed to protect webhook endpoints by verifying requests using various security mechanisms such as HMAC signatures, JWT tokens, static API keys, IP filtering, and optional mTLS verification. This node is beneficial for scenarios where secure and controlled access to webhook endpoints is required, such as integrating with trusted partners, enforcing replay protection, or validating identity tokens from identity providers.

Use Case Examples

  1. A company exposing a webhook endpoint that requires HMAC signatures with timestamp and nonce to prevent replay attacks.
  2. An enterprise using JWT tokens issued by an identity provider (Auth0, Okta) to authenticate webhook requests.
  3. A simple internal API where a static API key header is sufficient for authentication.
  4. A partner integration requiring HMAC signatures plus IP allow/deny lists for enhanced security.

Properties

Name Meaning
Security Profile Choose the authentication/protection profile for the webhook (HMAC, JWT, API Key, or Combo).
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 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, required for HMAC and Combo profiles.
HMAC Algorithm HMAC hash algorithm used for signature (SHA256 or SHA512), must match client and server.
IP Allow (CIDR, comma-separated) Comma-separated list of allowed IP networks in CIDR notation, used in Combo profile.
IP Deny (CIDR, comma-separated) Comma-separated list of denied IP networks in CIDR notation, checked before allow list in Combo profile.
Require Additional Static Header Enforces presence of a static header and value in addition to HMAC for defense-in-depth.
Static Header Name Name of the static header that must be present when required with HMAC.
Static Header Value Expected value of the static header, can be a secret.
JWT: Expected Issuer (optional) Expected 'iss' claim value in JWT tokens; empty allows any issuer (not recommended).
JWT: Audience (optional) Expected 'aud' claim value in JWT tokens; empty allows any audience (not recommended).
Signature Mode Determines what is signed in HMAC: either raw body only or extended mode including method, path, query, timestamp, nonce, and body hash.
Dual-Key Rotation: Previous Secret Optional previous secret key accepted during a dual-key rotation window for rolling key updates.
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, ideally ending with a colon.
JWKS Cooldown (ms) Minimum interval between JWKS fetches to reduce network load and control key rotation speed.
JWKS Fetch Timeout (ms) Timeout for retrieving JWKS keys; too short may cause false alarms.
Require mTLS (check proxy headers) Requires proof from upstream proxy that mutual TLS succeeded, validated via headers.
mTLS Verify Header Header name set by proxy on successful mTLS, default '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 DN must match; failure to match or regex errors cause check to fail closed.
Audit Export Controls optional export of metadata (without payload) to an HTTPS endpoint for audit logging.
Audit Endpoint URL Target URL for audit export, used if audit mode is HTTPS POST.
Audit Bearer Token (optional) Optional bearer token sent as Authorization header for audit endpoint.

Output

JSON

  • status - Status of the webhook request processing (e.g., accepted, rejected).
  • reason - Reason for rejection or additional information about the request.
  • metadata - Optional metadata about the request for audit or logging purposes.

Dependencies

  • Optional Redis server for replay protection and rate limiting.
  • Optional JWKS URL for JWT verification.

Troubleshooting

  • 413 error: Request body exceeds the configured maximum size; increase 'Max Body (bytes)' or reduce payload size.
  • 415 error: Content-Type header missing or not in allowed list; ensure request has correct Content-Type.
  • 429 error: Rate limit exceeded; reduce request frequency or increase 'Rate Limit / Minute'.
  • HMAC signature verification failures: check that client and server use the same HMAC algorithm and signature mode, and that timestamp and nonce are valid and within allowed skew.
  • JWT verification failures: ensure JWT token is valid, not expired, and matches expected issuer and audience if configured.
  • IP allow/deny misconfiguration: verify CIDR lists are correct and do not unintentionally block legitimate clients.
  • mTLS verification failures: ensure upstream proxy sets required headers and client certificate DN matches regex if configured.
  • Redis connection issues: verify Redis URL and credentials if Redis is enabled.

Links

Discussion