Secure Webhook (HMAC) icon

Secure Webhook (HMAC)

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)

AI-generated

Overview

This node implements a secure webhook with HMAC-based authentication and protection profiles. It is designed to verify incoming webhook requests using HMAC signatures, JWT tokens, API keys, or a combination of HMAC and IP allow/deny lists. This node is beneficial for scenarios where secure and authenticated webhook endpoints are required, such as integrating with external services that send sensitive data or require strict access control. Practical examples include validating webhook calls from trusted partners using HMAC signatures with replay protection, verifying JWT tokens issued by identity providers like Auth0 or Okta, or enforcing IP-based access control alongside HMAC authentication for enhanced security.

Use Case Examples

  1. A company receives webhook notifications from a payment gateway and uses this node to verify the HMAC signature and timestamp to prevent replay attacks.
  2. An enterprise uses JWT tokens issued by their identity provider to authenticate webhook requests securely.
  3. A partner VPN setup uses the combo profile to allow only specific IP ranges and verify HMAC signatures for incoming webhooks.

Properties

Name Meaning
Security Profile Choose the authentication and protection profile for the webhook, such as HMAC, JWT, API Key, or a combination with IP allow/deny.
Webhook Path Unique path segment(s) for the webhook URL without a leading slash.
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 every 60 seconds.
Timestamp Header Header name containing UNIX time in seconds 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 to prevent replay attacks.
HMAC Signature Header Header name for the HMAC signature, required for HMAC and combo profiles.
HMAC Algorithm HMAC hash algorithm used for signature verification (SHA256 or SHA512).
IP Allow (CIDR, comma-separated) List of allowed IP networks or addresses in CIDR notation, checked after deny list.
IP Deny (CIDR, comma-separated) List of denied IP networks or addresses in CIDR notation, checked before allow list.
Require Additional Static Header Enforce 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 with HMAC.
Static Header Value Expected value of the static header.
JWT: Expected Issuer (optional) Expected issuer value in the JWT token for validation.
JWT: Audience (optional) Expected audience value in the JWT token for validation.
Signature Mode Mode of signature calculation: 'Body only' signs raw body; 'Extended' signs method, path, query, timestamp, nonce, and body hash.
Dual-Key Rotation: Previous Secret Optional previous secret key accepted within a dual-key rotation window.
Dual-Key Window (minutes) Time window during which the previous secret is accepted for key rotation.
Enable Redis (Replay & Rate) Enable Redis for replay protection and rate limiting, recommended for high availability.
Redis URL Connection URL for Redis server.
Redis Namespace Namespace prefix for Redis keys.
JWKS Cooldown (ms) Minimum interval between JWKS fetches to reduce network load.
JWKS Fetch Timeout (ms) Timeout for retrieving JWKS keys.
Require mTLS (check proxy headers) Require proof from upstream proxy that mTLS succeeded.
mTLS Verify Header Header name set by proxy on successful mTLS.
mTLS Subject Header (optional) Header containing the Distinguished Name of the client certificate.
Subject Allow Regex (optional) Regex pattern that the DN must satisfy for mTLS validation.
Audit Export Controls export of metadata to an HTTPS endpoint for audit purposes.
Audit Endpoint URL URL of the audit export endpoint.
Audit Bearer Token (optional) Optional bearer token for authenticating audit export requests.

Output

JSON

  • status - Status of the webhook request processing (e.g., accepted, rejected).
  • reason - Reason for rejection or additional information about the request.
  • headers - Headers received in the webhook request.
  • body - Parsed body content of the webhook request.
  • clientIp - IP address of the client making the request.
  • timestamp - Timestamp of the request as extracted from headers or server time.

Dependencies

  • An API key credential for HMAC shared secret authentication
  • Optional Redis server for replay protection and rate limiting
  • JWKS URL for JWT verification

Troubleshooting

  • Common issues include clock skew causing replay protection failures; adjust 'Max Skew' setting accordingly.
  • Incorrect or missing HMAC signature header leads to request rejection; ensure client sends correct signature header.
  • IP allow/deny misconfiguration can block legitimate requests; verify CIDR lists carefully.
  • Rate limiting may cause 429 errors if request volume exceeds configured limits; adjust 'Rate Limit / Minute' as needed.
  • JWT verification failures due to incorrect issuer or audience settings; verify JWT claims and node configuration.
  • mTLS header checks may fail if upstream proxy is not configured to set required headers.

Links

Discussion