What does the admission webhook receive?

The control plane sends federatedGraphId, organizationId, and a short-lived privateConfigUrl. Your webhook fetches the config from that URL, validates it, and returns an HMAC-SHA256 signature or an error.

How long is the private config URL valid?

The privateConfigUrl token is short-lived and expires after 5 minutes. Once validation succeeds, the URL returns a 404. This ensures configs are fetched during validation, not later.

What happens if my admission webhook returns an error?

Return a 400 status with an error property. This blocks the composition from being made available to the router. The error appears in the Cosmo Studio composition detail page.

How does the router verify the signature?

Configure graph.sign_key in the router YAML with the same key used in the admission server. The router calculates the HMAC-SHA256 hash locally and compares it to the stored signature. A mismatch causes the configuration to be rejected.

What happens if the router receives a tampered configuration?

The router rejects the configuration and continues operating on the last known-good configuration. If no valid configuration exists, the router refuses to start.

Can I verify that admission webhook requests come from Cosmo?

Yes. Set --admission-webhook-secret when creating the federated graph. The control plane includes an HMAC-SHA256 signature in the X-Cosmo-Signature-256 header. Your server verifies this signature before processing the request.

Which router version is required?

Config Signing is available since Router version 0.74.0.

Config Signing for GraphQL Router | Cosmo by WunderGraph

The problem

Router configurations are trusted implicitly

A configuration that specifies subgraph URLs and execution rules is a high-value target. Without verification, the router applies whatever it receives.

Router configurations specify subgraph URLs

A tampered configuration can redirect traffic to a different server. The router has no way to detect the modification and applies the malicious config silently.

CDN-fetched configs have no built-in integrity check

When the router polls a CDN for configuration, it trusts whatever it receives. A compromised CDN or man-in-the-middle can deliver a modified config with no warning.

Custom validation logic has nowhere to run

Teams that want to verify subgraph URLs belong to their domain have no integration point. The config is applied as-is with no hook for business-specific validation rules.

Our solution

A cryptographic chain of trust from composition to router

Your admission server validates and signs every composition. The router verifies the signature before applying any config. A modification anywhere in the chain breaks the signature.

From composition to verified deployment

When a composition occurs, the control plane calls your admission webhook at /validate-config with a short-lived private URL (5-minute expiry) to fetch the configuration.
Your admission server fetches the config from the private URL, validates it according to your policies (e.g., checking that all subgraph URLs belong to your domain), and calculates an HMAC-SHA256 hash using your signing key.
The server returns the BASE64-encoded HMAC-SHA256 signature with a 200 status, or a 400 with an error message to block deployment.
The control plane stores the signature with the configuration artifact and makes it available to the router.
When the router fetches or loads a configuration, it independently calculates the HMAC-SHA256 hash and compares it to the stored signature.
If the signatures match, the configuration is applied. A mismatch causes the router to reject the configuration and continue on the last known-good config.

Available since Router 0.74.0. Works with CDN polling and file-based config.

Config Signing

Before & After

Before Cosmo	With Cosmo
Configurations trusted implicitly with no verification	HMAC-SHA256 signature verified before every config apply
No protection against CDN or file system tampering	Any modification produces a signature mismatch and rejection
No way to enforce custom subgraph URL policies	Admission webhook runs your validation before signing
Router applies modified configs silently	Router rejects tampered configs and keeps last known-good

Webhook authentication

Bidirectional verification

The control plane includes an X-Cosmo-Signature-256 header on every admission webhook request. Your server verifies this signature using the --admission-webhook-secret to confirm requests originate from Cosmo before processing them.

How Config Signing works in Cosmo

01

Triggered on every composition.

Compose

A schema composition occurs on the control plane. The control plane calls your admission webhook at /validate-config with federatedGraphId, organizationId, and a short-lived privateConfigUrl (5-minute expiry). Requires a publicly accessible HTTPS admission server.

02

Your logic. Your policies.

Validate

Your admission server fetches the config from the privateConfigUrl. It validates according to your policies — for example, verifying all subgraph URLs belong to your organization's domain. Returns 400 with an error to block deployment, or proceeds to signing.

03

HMAC-SHA256. BASE64. 200 OK.

Sign

Your server calculates an HMAC-SHA256 hash of the configuration content using the shared signing key. It returns the BASE64-encoded signature as signatureSha256 in a 200 response. The control plane stores this signature with the artifact.

04

Reject on mismatch. No exceptions.

Verify

The router loads the config and the stored signature. It independently calculates the HMAC-SHA256 hash using the same signing key (configured as graph.sign_key). If the hashes match, the config is applied. A mismatch causes rejection.

Signing controls

Your webhook. Your validation rules.

Works with CDN polling and file-based config deployment.

Custom validation logic

Your admission webhook fetches the config from a short-lived private URL and validates it using your own rules. Block compositions that contain unauthorized subgraph URLs, unexpected changes, or policy violations.

HMAC-SHA256 signatures

Your server computes an HMAC-SHA256 hash of the configuration and returns the BASE64-encoded result. The same algorithm runs on the router side to verify the signature before applying the config.

Works with CDN and file-based deployment

Config Signing works whether the router polls a CDN or loads a config from a file. For file-based deployment, pass --graph-sign-key to the wgc router fetch command.

Studio visibility

Failed validations are visible on the composition detail page in Cosmo Studio. Teams can see blocked compositions and the error message returned by the admission webhook.

Add cryptographic verification to your router configs

Deploy an admission webhook. Sign every composition. The router rejects anything that doesn't verify.

Start Free Read the Docs

Detect tampered router configurations before they apply