Mutual TLS for Webhooks
When Atomic delivers a webhook, the roles from API mTLS are reversed: Atomic is the client and your webhook endpoint is the server. With mutual TLS enabled, Atomic presents a client certificate on every delivery, and your server verifies it against Atomic's certificate authority (CA) before accepting the request.
Webhook mTLS is optional and works alongside the HMAC signature Atomic includes on every webhook. Verifying the signature confirms the payload came from Atomic and was not modified. mTLS additionally rejects connections from anyone else before a request body is ever read.
Atomic's client certificate
Atomic issues webhook client certificates from its own private PKI. Each customer and environment gets a distinct certificate with its own Common Name, so you can tell sandbox and production deliveries apart at the TLS layer if you want to.
| Attribute | Value |
|---|---|
| Issuer chain | Leaf certificate, issued by Atomic FI Issuing CA, which is issued by Atomic FI Root CA |
| Key algorithm | ECDSA P-384 |
| Subject CN (sandbox) | <your-company>.webhook.atmcsbx.com |
| Subject CN (production) | <your-company>.webhook.atomicfi.com |
| Subject Alternative Name | dNSName matching the CN |
| Extended Key Usage | clientAuth |
| Validity | 13 months. Atomic renews before expiry. |
| Revocation | CRL and OCSP URLs are embedded in the certificate. |
Atomic shares the public leaf certificate, the issuing CA certificate, and the root CA certificate with you, all in PEM format. Atomic's private key never leaves Atomic's key management system.
Setting up your endpoint
- Ask your Atomic representative to enable webhook mTLS for the environment you are working in. Start with sandbox.
- Atomic sends you the CA chain (root and issuing CA certificates), the public leaf certificate, and the CN it carries.
- Install the Atomic FI Root CA and Atomic FI Issuing CA certificates in the trust store your webhook endpoint uses for client authentication, and configure the endpoint to require a client certificate.
- Optionally, authorize or route on the certificate's CN, for example to send sandbox deliveries to a test environment.
- Send a test event from the Console webhooks page and confirm your endpoint accepts it. Then confirm a request without a client certificate is rejected.
- Repeat for production.
X-HMAC-Signature-Sha-256 header after enabling mTLS. The two controls protect against different things. Renewal: trust the chain, not the leaf
Atomic's leaf certificate is replaced before it expires. How much that affects you depends on what your endpoint trusts:
- If you trust the Atomic CA chain (recommended), renewals are transparent. The new leaf is issued by the same CA with the same CN, so your endpoint keeps accepting deliveries with no change on your side.
- If you pin the leaf certificate or its fingerprint, every renewal requires you to install the new certificate before the old one expires. Atomic will share the renewed certificate ahead of time, but pinning the leaf makes an outage possible if the update is missed. Prefer trusting the chain and, if you need a stable identifier, match on the CN.
The Atomic CA certificates themselves are long-lived. Atomic will notify you well ahead of any change to the CA chain.
Using your own CA instead
Some institutions require that client certificates presented to their systems be issued by their own PKI. Atomic supports this. Atomic generates the key pair, sends you a certificate signing request (CSR) per environment, and installs the certificate your CA returns. Your CA profile must permit the clientAuth key usage. Atomic can generate ECDSA P-256 or P-384 keys to match your CA's requirements.
In this model, renewal follows your CA's process: Atomic sends a new CSR before expiry and you return a new certificate.