TLS configuration for webhook endpoints

Webhook TLS problems are unusually expensive because they are silent on the way in and loud on the way out. A sender with certificate verification switched off delivers successfully to an attacker for months without a single error log; a consumer whose certificate quietly expired on a Saturday discovers it on Monday, along with a queue of failed deliveries and a support thread. This page covers the transport layer on both ends of a webhook exchange, as the third leg of webhook endpoint hardening alongside preventing SSRF in outbound webhook delivery, which governs where you may connect while this one governs how that connection is established and trusted.

Keep three verifications separate in your head, because a single configuration flag usually disables all three at once and engineers rarely intend that. Chain verification asks whether a CA you trust signed this certificate. Hostname verification asks whether this certificate was issued for the host you asked for. Validity verification asks whether the certificate is inside its notBefore/notAfter window. Any one of them failing must fail the delivery, and none of them is optional in production.

Prerequisites

• Runtime: Node.js 20+ with TypeScript 5, undici 6 as the HTTP client, and node:tls for the certificate probe.
• OpenSSL 3 on the machines you debug from, for s_client inspection.
• Endpoint records that can carry per-endpoint configuration — you will need somewhere to store a private CA bundle and an exception expiry date against a single consumer’s endpoint.
• A metrics pipeline that accepts gauges, for days-until-expiry per endpoint.
• Testing: Vitest 1, plus a locally generated self-signed certificate to prove your rejection path actually rejects.

Step 1: Set the protocol floor and cipher policy

Runtime defaults drift. A Node minor release can change the default cipher list, and a base image update can change the OpenSSL policy underneath it — so put the policy in your repository where a code review can see it. For webhook delivery the floor is TLS 1.2, the preference is TLS 1.3, and everything below 1.2 is refused rather than negotiated.

TLS 1.3 is worth preferring for two operational reasons beyond cryptographic hygiene: it completes in one round trip instead of two, which matters when you are opening thousands of short-lived connections to distinct consumers, and its cipher suite list is small and entirely forward-secret, which removes a whole category of configuration mistake.

import { Agent } from 'undici';

// TLS 1.3 suites are fixed by the protocol; this list only affects a 1.2
// downgrade. Every entry is ECDHE, so forward secrecy holds on both paths.
const TLS12_CIPHERS = [
  'ECDHE-ECDSA-AES128-GCM-SHA256',
  'ECDHE-RSA-AES128-GCM-SHA256',
  'ECDHE-ECDSA-AES256-GCM-SHA384',
  'ECDHE-RSA-AES256-GCM-SHA384',
  'ECDHE-ECDSA-CHACHA20-POLY1305',
  'ECDHE-RSA-CHACHA20-POLY1305',
].join(':');

export function createDeliveryAgent(): Agent {
  return new Agent({
    connect: {
      minVersion: 'TLSv1.2',       // refuse 1.0 and 1.1 outright
      maxVersion: 'TLSv1.3',       // negotiate 1.3 whenever the peer supports it
      ciphers: TLS12_CIPHERS,
      honorCipherOrder: true,
      // rejectUnauthorized defaults to true — never set it to false here.
    },
    connectTimeout: 3_000,
    headersTimeout: 5_000,
    bodyTimeout: 10_000,
    keepAliveTimeout: 10_000,
    keepAliveMaxTimeout: 60_000,
  });
}

Engineering note: publish your floor in consumer documentation. A partner still terminating TLS 1.0 on a legacy appliance needs to know at integration time, not when their first delivery fails with an unhelpful EPROTO.

Step 2: Keep chain verification on, always

rejectUnauthorized: false is the most damaging two words in a webhook codebase. It usually enters as a temporary workaround for one consumer with a broken certificate, gets committed because the delivery started working, and then applies to every endpoint the agent serves. From that moment anyone able to intercept the connection can present any certificate and receive your signed payloads — and because the delivery succeeds, no metric, no log line and no alert fires. It is a vulnerability whose only symptom is that everything looks fine.

The same objection applies to NODE_TLS_REJECT_UNAUTHORIZED=0 in an environment file, which is worse still because it is invisible in code review. Ban both, and make the ban enforceable: fail CI on a grep, and assert at boot that the process is not running with verification disabled.

import { Agent, request } from 'undici';

export class TlsVerificationError extends Error {
  constructor(readonly code: string, readonly endpoint: string) {
    super(`tls_verification_failed:${code}`);
  }
}

// Boot-time assertion: a misconfigured environment must not start.
export function assertTlsHardened(): void {
  if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
    throw new Error('refusing to start: NODE_TLS_REJECT_UNAUTHORIZED is disabled');
  }
}

const VERIFICATION_CODES = new Set([
  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
  'SELF_SIGNED_CERT_IN_CHAIN',
  'DEPTH_ZERO_SELF_SIGNED_CERT',
  'CERT_HAS_EXPIRED',
  'ERR_TLS_CERT_ALTNAME_INVALID',
  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
]);

export async function deliver(url: URL, body: string, dispatcher: Agent) {
  try {
    return await request(url, { method: 'POST', body, dispatcher, maxRedirections: 0 });
  } catch (err) {
    const code = (err as NodeJS.ErrnoException).code ?? 'UNKNOWN';
    if (VERIFICATION_CODES.has(code)) {
      // A distinct reason code turns "delivery failed" into an actionable
      // message the consumer can fix themselves.
      throw new TlsVerificationError(code, url.host);
    }
    throw err;
  }
}

Engineering note: map each verification code to consumer-facing copy. CERT_HAS_EXPIRED and ERR_TLS_CERT_ALTNAME_INVALID have completely different fixes, and a delivery log that says only “connection error” guarantees a support ticket.

Step 3: Verify the hostname against the SAN

Chain verification alone proves someone with a trusted CA signature holds this certificate — not that it belongs to the host you meant to reach. Hostname verification closes that, matching the requested host against the certificate’s subjectAltName entries. The legacy commonName field is no longer consulted by modern clients, so a consumer whose certificate carries only a CN will fail here even though it “looks right” in a browser they tested with years ago.

Two things must agree: the SNI value you send during the handshake, and the name you check the certificate against. If you followed the address-pinning approach from the SSRF page, this is exactly where it matters — the socket connects to a validated IP while SNI and identity checking both continue to use the hostname.

import tls from 'node:tls';
import { Agent } from 'undici';

export function agentForHost(hostname: string): Agent {
  return new Agent({
    connect: {
      servername: hostname,     // SNI: virtual hosts return the right certificate
      minVersion: 'TLSv1.2',
      checkServerIdentity: (host, cert) => {
        // Wrap the default check; never replace it. Returning undefined from a
        // hand-written implementation silently accepts every certificate.
        const err = tls.checkServerIdentity(hostname, cert);
        if (err) return err;
        if (!cert.subjectaltname) {
          return new Error(`certificate for ${host} has no subjectAltName`);
        }
        return undefined;
      },
    },
  });
}

Engineering note: a consumer using an IP address as their webhook host needs the address in the SAN as an IP: entry, which most public CAs will not issue. In practice this means hostname-only endpoints, which is a rule worth enforcing at registration alongside the checks in preventing SSRF in outbound webhook delivery.

Step 4: Trust a private CA per endpoint, never globally

Some consumers genuinely cannot present a publicly trusted certificate: an endpoint inside a corporate network, a regulated environment with an internal PKI, a partner whose appliance only supports their own root. The wrong answer is to disable verification. The right answer is to trust their CA, for their endpoint, and for nothing else.

Scope it three ways. Scope it by endpoint, so a dispatcher built for one consumer carries their bundle and no other. Scope it in time, with an expiry date on the exception that forces a review rather than letting it become permanent. Scope it in visibility, by listing every active exception on a dashboard so the count is a number someone owns and drives down.

import { Agent } from 'undici';

interface EndpointRecord {
  id: string;
  url: string;
  privateCaPem: string | null;
  caExceptionExpiresAt: string | null; // ISO date; null when no exception exists
}

export function dispatcherFor(endpoint: EndpointRecord, now = new Date()): Agent {
  const base = {
    minVersion: 'TLSv1.2' as const,
    servername: new URL(endpoint.url).hostname,
  };
  if (!endpoint.privateCaPem) return new Agent({ connect: base });

  const expiresAt = endpoint.caExceptionExpiresAt
    ? new Date(endpoint.caExceptionExpiresAt)
    : null;
  if (!expiresAt || expiresAt < now) {
    // An expired exception is not a grace period. Fail the delivery and let the
    // renewal conversation happen, rather than extending it silently forever.
    throw new Error(`ca_exception_expired:${endpoint.id}`);
  }
  return new Agent({
    connect: {
      ...base,
      // ADD this CA for this endpoint. Verification stays fully enabled: the
      // chain must still validate, and the hostname must still match the SAN.
      ca: [endpoint.privateCaPem],
    },
  });
}

Engineering note: pin the root, not the leaf. Pinning a leaf certificate means the delivery breaks every time the consumer renews, typically every ninety days, and the pressure that creates is what eventually pushes someone to disable verification instead.

Step 5: Monitor certificate expiry and handshake failures

Certificate expiry is the most predictable outage in this entire area and still the most common. Ninety-day certificates plus a renewal automation that silently stopped equals a webhook integration that dies on a specific afternoon. Because you know the expiry date in advance, you can turn it into a gauge and alert on it long before it becomes a delivery failure — and you are often better placed to notice than the consumer is.

Probe each registered endpoint on a schedule, read notAfter from the peer certificate, and export days-remaining per endpoint. Escalate in stages: a ticket at 30 days, an email to the endpoint owner at 14, a page to your own on-call at 3, because at that point you are about to start failing deliveries and queueing retries. Feed the same signal into the failure alerting described in alerting on webhook delivery failures so a certificate expiry and a generic outage do not look identical on the dashboard.

import tls from 'node:tls';

export interface CertHealth {
  host: string;
  daysRemaining: number;
  issuer: string;
  protocol: string | null;
}

export function probeCertificate(host: string, port = 443): Promise<CertHealth> {
  return new Promise((resolve, reject) => {
    const socket = tls.connect(
      { host, port, servername: host, minVersion: 'TLSv1.2', timeout: 5_000 },
      () => {
        const cert = socket.getPeerCertificate();
        if (!cert || !cert.valid_to) {
          socket.destroy();
          return reject(new Error(`no_peer_certificate:${host}`));
        }
        const expiresAt = new Date(cert.valid_to).getTime();
        resolve({
          host,
          daysRemaining: Math.floor((expiresAt - Date.now()) / 86_400_000),
          issuer: cert.issuer?.O ?? 'unknown',
          protocol: socket.getProtocol(),
        });
        socket.end();
      },
    );
    socket.on('timeout', () => socket.destroy(new Error(`tls_timeout:${host}`)));
    socket.on('error', reject);
  });
}

export function severityFor(days: number): 'ok' | 'ticket' | 'email' | 'page' {
  if (days > 30) return 'ok';
  if (days > 14) return 'ticket';
  if (days > 3) return 'email';
  return 'page';
}

Engineering note: probe the endpoint’s real hostname and port, not a health-check URL on a different host. Large consumers frequently terminate webhook traffic on a different load balancer from their main site, with a different certificate and a different renewal owner.

Verification and testing

Start from the wire. openssl s_client tells you the negotiated protocol, the cipher, the chain, and the verification result in one command — and it answers questions your application logs cannot.

# Negotiated protocol, cipher and verification result in one shot.
openssl s_client -connect hooks.acme.io:443 -servername hooks.acme.io -brief </dev/null

# Prove the floor holds: this MUST fail against a correctly configured peer.
openssl s_client -connect hooks.acme.io:443 -tls1_1 </dev/null

# Read the validity window without wading through the full certificate.
openssl s_client -connect hooks.acme.io:443 -servername hooks.acme.io </dev/null \
  | openssl x509 -noout -dates -ext subjectAltName

Then pin the behaviour in tests, using a locally generated self-signed certificate so the rejection path is exercised on every run rather than assumed.

import { describe, expect, it } from 'vitest';
import { severityFor, probeCertificate } from './tls';
import { deliver, createDeliveryAgent } from './delivery';

describe('tls policy', () => {
  it('rejects a self-signed certificate rather than delivering to it', async () => {
    const agent = createDeliveryAgent();
    // Local server started with a self-signed cert on 127.0.0.1:8443.
    await expect(
      deliver(new URL('https://localhost:8443/webhooks'), '{}', agent),
    ).rejects.toThrow(/tls_verification_failed/);
  });

  it('escalates by remaining lifetime', () => {
    expect(severityFor(45)).toBe('ok');
    expect(severityFor(20)).toBe('ticket');
    expect(severityFor(7)).toBe('email');
    expect(severityFor(1)).toBe('page');
  });

  it('reports the negotiated protocol for a healthy endpoint', async () => {
    const health = await probeCertificate('hooks.acme.io');
    expect(health.protocol).toMatch(/TLSv1\.[23]/);
    expect(health.daysRemaining).toBeGreaterThan(0);
  });
});

A useful CI addition is a grep gate: fail the build if rejectUnauthorized: false, NODE_TLS_REJECT_UNAUTHORIZED, or -k in a delivery script appears anywhere outside a test fixture directory. It is a crude check that catches the exact regression that matters most.

Failure modes and gotchas

• Verification disabled for one consumer, applied to everyone. A single rejectUnauthorized: false on a shared agent removes chain, hostname and expiry checking for every endpoint that agent serves, and every delivery keeps returning 200. Scope trust per endpoint with an explicit CA bundle and let the exception expire.
• A hand-written checkServerIdentity that returns undefined. Replacing the default identity check with a custom function that forgets to call tls.checkServerIdentity accepts any valid certificate for any host — a strictly worse outcome than having no custom check. Always wrap the default and return its error first.
• Pinning a leaf certificate instead of a root. The pin breaks on every renewal, usually at ninety-day intervals and usually out of hours. Pin the issuing root, and if the consumer’s root itself rotates, treat that as a scheduled change with the same care as the range rollover in IP allowlisting and egress controls for webhooks.
• Missing intermediate certificates on the consumer’s server. The chain validates in a browser, which caches intermediates from earlier visits, and fails in your dispatcher, which does not. The symptom is UNABLE_TO_VERIFY_LEAF_SIGNATURE against a certificate everyone insists is fine; the fix is on their server, sending the full chain.
• Expiry monitored on the wrong host. Probing the consumer’s marketing domain rather than their webhook host means a green dashboard while the actual endpoint’s certificate expires. Probe exactly the host and port stored on the endpoint record.

Frequently Asked Questions

Related

• Preventing SSRF in outbound webhook delivery
• IP allowlisting and egress controls for webhooks
• Webhook Endpoint Hardening
• Configuring mTLS for webhook endpoints