Webhook signatures in Mesh

What signed webhooks are, why they matter, and what your team can expect when ComplyAdvantage delivers them.

What this means for you

ComplyAdvantage Mesh can now sign every webhook it sends so that your systems can be confident the request really came from us and that no one tampered with the payload along the way. Signing follows the open Standard Webhooks v1 specification and uses HMAC-SHA256, a widely supported and well-trusted method.

Signatures are opt-in per Mesh account. If your account has signing enabled, every webhook we send for that account carries a signature your developers can verify before processing the event. If you have not opted in, your webhooks continue to be delivered exactly as before — nothing changes for you until you decide you want signatures.

Why it matters

• Authenticity — the signature confirms that ComplyAdvantage sent the webhook and not someone impersonating us.

• Integrity — if any byte of the payload is modified in transit, the signature will no longer match and your system can reject the request.

• Replay protection — each webhook is signed together with a timestamp, so old requests cannot be quietly resent later.

• Standards-based — the scheme matches the public Standard Webhooks v1 specification, so your developers can use off-the-shelf libraries to verify signatures.

How it works at a glance

When signing is enabled for your account, every webhook delivered from Mesh includes three additional HTTP headers that together let your system verify the request:

webhook-id

webhook-timestamp

webhook-signature

Your developers combine the id, the timestamp, and the original request body and recompute the HMAC-SHA256 using your account's signing secret. If their computed signature matches the one in the header, the webhook is genuine. If it does not match, your system should reject the request.

Getting started

Signing is provisioned per Mesh account. To enable it, ask your ComplyAdvantage Customer Success Manager or open a support request with the following details:

• The Mesh region you are hosted in (for example EU, US, CA, AU).

• The account identifier(s) you want signed webhooks enabled for.

Once your request is picked up, the support team generates a 256-bit signing secret for the account and shares it with you securely. Please do not include the secret in the support ticket itself — the team will share it through an approved secure channel.

From the moment the secret is created, every webhook we send for the account is signed. Accounts without a secret continue to receive unsigned webhooks.

Rotating your signing secret

Regular rotation of signing keys is good security practice, and you can request a rotation whenever you need one — for example on a routine schedule, after a personnel change, or if you suspect a secret has been exposed. Rotation happens without downtime.

How it works:

1. You ask ComplyAdvantage to start a rotation.

2. We generate a second secret for your account and share it with you securely. Both secrets are now active.

3. During the overlap window, every webhook is signed with both secrets, so verification keeps working whether your systems are still using the old secret or have switched to the new one.

4. Once you confirm you are fully on the new secret, we delete the old one. From that point each webhook is signed with the new secret only.

An account can hold at most two active signing secrets at a time — one to retire, one to keep — which is exactly what the rotation flow needs.

Turning signatures off

If you ever need to stop signing webhooks for an account — for example while you re-platform — your CSM or support contact can remove the signing secret. With no secret on the account, webhooks revert to being delivered unsigned. You can re-enable signing at any time by requesting a new secret.

What your developers need to do

Verifying a Mesh webhook signature is usually a few lines of code. Because the scheme follows Standard Webhooks v1, your team can either implement the verification themselves or use one of the many open-source Standard Webhooks libraries.

Implementation details are available in the Mesh developer documentation:

Mesh Webhooks documentation — https://docs.mesh.complyadvantage.com/docs/webhooks

Things to know

It is opt-in per account

Signing is enabled at the Mesh account level. If you have multiple accounts, each one needs its own signing secret. Accounts you do not opt in continue to receive unsigned webhooks.

Source IPs still apply

Signatures complement — they do not replace — the source IP allow-list for your region. Both controls layer well together.

At-least-once delivery, with retries

Mesh webhooks are delivered with an at-least-once guarantee and may retry on failures. Each delivery — including retries — is signed, and each delivery has its own webhook-id, so your handler can stay idempotent and still rely on signatures for security.

Timestamps and replay protection

Standard Webhooks recommends rejecting webhooks whose timestamp is more than five minutes outside the current time, to prevent replays of old captured requests. Your developers can implement this check alongside the signature check.

Where to get help

For anything related to enabling, rotating, or disabling webhook signatures for your account — and for help if your developers report verification problems — contact your ComplyAdvantage Customer Success Manager or raise a request through the support portal.

Reference: Standard Webhooks v1 specification — https://www.standardwebhooks.com/