Step by Step Guide to solve n8n webhook SSL errors
Who this is for: n8n developers and DevOps engineers who receive TLS‑related errors when a webhook node calls an external endpoint. We cover this in detail in the n8n Webhook Errors.
Quick Diagnosis
| Quick Fix | When to Use | How to Apply |
|---|---|---|
| Use a trusted certificate | Public domain you control | Install a valid SSL cert from Let’s Encrypt, DigiCert, etc. |
| Add missing intermediate CA | Self‑signed or corporate‑issued cert | Concatenate fullchain.pem (cert + intermediates) and point the web server to it. |
| Tell Node.js to trust extra CAs | Private CA, internal network | Set NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt in the n8n container or service. |
| Temporarily disable verification (not for production) | Quick test on localhost | Export NODE_TLS_REJECT_UNAUTHORIZED=0 before starting n8n. |
Result: The webhook call succeeds and the workflow proceeds without SSL‑related failures.
1. Why n8n Encounters SSL Errors
If you encounter any authentication failure resolve them before continuing with the setup.
When a webhook node forwards a payload, Node.js validates the TLS handshake using its built‑in CA store. Any mismatch between the server’s certificate chain and Node’s trust store triggers an error.
| Error Type | Typical Cause | Example Message |
|---|---|---|
| Self‑signed / private CA | Certificate not signed by a public root | UNABLE_TO_VERIFY_LEAF_SIGNATURE |
| Expired certificate | Not After date passed |
certificate has expired |
| Hostname mismatch | CN/SAN does not match requested host | Hostname/IP does not match certificate's altnames |
| Missing intermediate chain | Only leaf cert provided | unable to get local issuer certificate |
| Unsupported TLS version | Server forces TLS 1.0/1.1 | SSL routines:tls_process_server_certificate:unsupported protocol |
n8n does not alter TLS verification; the fix is always to correct the certificate or adjust Node.js trust settings.
2. Step‑by‑Step Fixes
If you encounter any cors policy block resolve them before continuing with the setup.
2.1. Verify the Certificate Chain
# Replace with your webhook URL openssl s_client -showcerts -connect webhook.example.com:443 </dev/null
- Look for
Verify return code: 0 (ok). - If you see
unable to get local issuer certificate, the chain is incomplete.
2.2. Deploy a Proper Certificate
| Situation | Action |
|---|---|
| Public domain | Use Let’s Encrypt (free). Example: |
| Internal service | Generate a CSR, sign with your corporate CA, then export the full chain (fullchain.pem). |
| Legacy system only supports self‑signed | Keep the cert but add the CA to n8n’s trust store (see 2.4). |
certbot certonly --standalone -d webhook.example.com
EEFA: Never expose a self‑signed cert to the public internet; it defeats TLS security.
2.3. Configure the Web Server to Use the Full Chain
If you terminate TLS with nginx or Apache, point the server to the combined file that includes the leaf and all intermediates.
# nginx snippet (only the SSL directives) ssl_certificate /etc/ssl/certs/fullchain.pem; # cert + intermediates ssl_certificate_key /etc/ssl/private/privkey.pem;
Restart the web server, then repeat the openssl test to confirm a clean handshake.
2.4. Instruct Node.js to Trust a Private CA
When the webhook server uses a private CA, add its root certificate to the Node.js trust store.
Docker‑Compose (split for readability)
Service definition
services:
n8n:
image: n8nio/n8n
ports:
- "5678:5678"
Mount the CA file
volumes:
- ./certs/company-ca.crt:/certs/company-ca.crt:ro
Expose the extra‑CA environment variable
environment:
- NODE_EXTRA_CA_CERTS=/certs/company-ca.crt
#### Stand‑alone (Linux/macOS)
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt n8n start
EEFA: Do not set
NODE_TLS_REJECT_UNAUTHORIZED=0in production. It disables all TLS verification, exposing every outbound request to potential MITM attacks.
2.5. Temporarily Bypass Verification (Debug Only)
export NODE_TLS_REJECT_UNAUTHORIZED=0 # ONLY for local debugging n8n start
Run the workflow once; the webhook should succeed. Immediately remove the variable and apply a proper certificate solution.
3. Troubleshooting Checklist
| Check | How to Verify | Remedy if Failing |
|---|---|---|
| Certificate is not expired | openssl x509 -noout -dates -in cert.pem |
Renew via Let’s Encrypt or your CA. |
| Hostname matches CN/SAN | openssl s_client -connect host:443 -servername host |
Update DNS or request a new cert with correct SAN. |
| Full chain served | Look for Certificate chain length > 1 in openssl s_client output. |
Concatenate leaf + intermediates → fullchain.pem. |
| Node trusts the CA | node -e "console.log(require('tls').rootCertificates.includes('Your CA'))" |
Set NODE_EXTRA_CA_CERTS or add CA to system store. |
| Proxy / corporate firewall stripping TLS | curl -v https://webhook.example.com from the same host. |
Bypass proxy or configure it to allow TLS passthrough. |
| TLS version mismatch | openssl s_client -tls1_2 -connect host:443 |
Upgrade server to support TLS 1.2+ or update Node version. |
4. Advanced: Using n8n’s “Webhook Test” with Custom TLS Settings
The UI’s Test button respects the same environment as the runtime. To make it trust your private CA:
- Open the workflow and select the Webhook node.
- Click Settings → Advanced.
- Add an environment variable:
Key Value NODE_EXTRA_CA_CERTS /data/certs/company-ca.crt - Save, Deploy, and press Test. The request should now succeed.
EEFA: Keep the CA file read‑only and outside version control to avoid leaking private certificates.
5. When to Escalate
| Symptom | Reason to Escalate |
|---|---|
| Error persists after full chain and CA trust configuration | Possible reverse proxy misconfiguration or HSTS preloading conflict. |
| Intermittent failures only on specific IP ranges | Likely network‑level TLS inspection by a corporate firewall. |
n8n logs show ERR_TLS_CERT_ALTNAME_INVALID despite correct cert |
DNS CNAME points to a different host; verify the final resolved IP. |
Provide the openssl dump and docker logs <container> to your DevOps or security team.
Next Steps
- Automating certificate renewal with Let’s Encrypt & Docker (see page).
- Securing webhook endpoints – IP whitelisting, HMAC signatures.
Conclusion
SSL/TLS errors in n8n webhook nodes stem from mismatched or incomplete certificate chains. The reliable fixes are:
- Deploy a fully‑chained, trusted certificate (Let’s Encrypt or corporate CA).
- Ensure the web server serves the full chain (
fullchain.pem). - When using a private CA, point Node.js to the extra CA bundle via
NODE_EXTRA_CA_CERTS.
Apply these changes in a staging environment first, then promote to production. Proper certificate management restores secure webhook communication and keeps your workflows running reliably.
