Secure Webhook (HMAC Combo) icon

Secure Webhook (HMAC Combo)

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

Secure Webhook (HMAC Combo)

AI-generated

Overview

This node implements a secure webhook with multiple authentication and protection profiles, including HMAC, JWT (JWKS), API Key, and a Combo mode that extends HMAC with 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 for APIs, integrating with enterprise identity providers, and protecting partner integrations with IP restrictions.

Use Case Examples

  1. A company exposes a webhook for receiving event notifications and uses the HMAC profile to ensure requests are authentic and not replayed.
  2. An enterprise uses the JWT profile to verify incoming webhook requests against their identity provider (e.g., Auth0) using JWKS keys.
  3. A partner integration uses the Combo profile to require HMAC signatures and restrict access to specific IP ranges for enhanced security.

Properties

Name Meaning
Security Profile Choose the authentication and protection profile for the webhook, such as HMAC, JWT, API Key, or Combo (HMAC + IP allow/deny).
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 with HTTP 413.
Allowed Content-Types Comma-separated list of allowed content types; requests missing or with disallowed content types are rejected with HTTP 415.
Rate Limit / Minute (per IP) Maximum number of requests allowed per IP address per 60 seconds; exceeding results in HTTP 429 with Retry-After header.
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 to prevent replay attacks.
Max Skew (seconds) Allowed clock skew between client and server timestamps to balance replay defense and false positives.
HMAC Signature Header Header name containing the HMAC signature; used in HMAC and Combo profiles.
HMAC Algorithm Hash algorithm used for HMAC signature, either SHA256 or SHA512.
IP Allow (CIDR, comma-separated) Comma-separated list of allowed IP networks in CIDR notation; checked after deny list; used in Combo profile.
IP Deny (CIDR, comma-separated) Comma-separated list of denied IP networks in CIDR notation; deny list is checked before allow list; 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 that must be present along with HMAC.
Static Header Value Expected value of the static header; treated as a 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 profiles: 'Body only' signs raw body; 'Extended' signs method, path, sorted query, timestamp, nonce, and body hash.
Dual-Key Rotation: Previous Secret Optional previous secret key accepted within the dual-key window for rolling key rotation.
Dual-Key Window (minutes) Time window during which the previous secret is accepted for key rotation.
Enable Redis (Replay & Rate) Enables Redis 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 Key namespace prefix for Redis keys.
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 client certificate DN must match; failure to match results in rejection.
Audit Export Controls optional export of metadata (without payload) to an HTTPS endpoint for audit logging.
Audit Endpoint URL Target HTTPS URL for audit export; relevant if audit export is enabled.
Audit Bearer Token (optional) Optional bearer token sent as Authorization header for audit endpoint.

Output

JSON

  • webhookUrl - The full URL of the secure webhook endpoint.
  • status - Status of the webhook setup or request processing (e.g., accepted, rejected).
  • reason - Reason for rejection or failure if applicable.
  • requestHeaders - Headers received in the webhook request.
  • requestBody - Parsed body of the webhook request.
  • clientIp - IP address of the client making the request.
  • rateLimitRemaining - Number of remaining allowed requests for the client IP in the current rate limit window.

Dependencies

  • An API key credential for HMAC shared secret authentication.
  • Optional Redis server for replay protection and rate limiting in clustered environments.

Troubleshooting

  • Common issues include clock skew causing replay protection failures; adjust 'Max Skew' to balance security and false positives.
  • Incorrect or missing headers (e.g., timestamp, nonce, signature) will cause request rejection with appropriate HTTP status codes.
  • Rate limiting may block legitimate requests if limits are too low; adjust 'Rate Limit / Minute' accordingly.
  • If using JWT profile, ensure JWKS URL is reachable and tokens have correct issuer and audience claims.
  • IP allow/deny lists in Combo profile must be correctly formatted CIDR strings; misconfiguration can block legitimate clients.
  • When enabling Redis, ensure the Redis URL and namespace are correctly configured and Redis is accessible.

Links

Discussion