What is a Subgraph Check Extension?

A Subgraph Check Extension is a webhook integration that lets you hook custom validation logic into the Cosmo schema check pipeline. When a schema check runs in a configured namespace, Cosmo sends a POST request to your endpoint with full context about the proposed change. You can return custom lint issues or errors that block deployment.

What data does my endpoint receive?

Your endpoint receives a JSON payload with organization context, namespace, subgraph details, VCS information (branch, commit SHA, author), and a list of affected federated graphs. A downloadable URL gives access to bulk data — including schema SDL versions, built-in lint issues, schema changes, and affected operations — for 5 minutes after the request.

How do I return custom lint issues?

Return HTTP 200 with a JSON body containing a lintIssues array. Each item should include lintRuleType, severity, message, and an issueLocation with line and column numbers. To explicitly fail the check, include entries in the errors array. To pass through with no additions, return HTTP 204.

How is the webhook secured?

Requests from Cosmo include an HMAC-SHA256 signature in the X-Cosmo-Signature-256 header. Verify the HMAC-SHA256 signature in the X-Cosmo-Signature-256 header using the secret key configured in Cosmo Studio.

What happens if my endpoint is unreachable?

See the Subgraph Check Extensions documentation for timeout and endpoint-failure behavior.

Is Subgraph Check Extensions available on the Free tier?

No. Subgraph Check Extensions require a Pro or Enterprise plan.

GraphQL Schema Validation Webhooks | Cosmo by WunderGraph

The problem

Built-in checks can't know your rules

Every organization has standards that no generic tool can anticipate — naming conventions, compliance requirements, team coordination workflows, and deprecation policies that are unique to your context.

Generic linting rules miss company-specific requirements

Built-in validation tools are powerful, but they can't anticipate every organization's policies. Naming conventions, deprecation formats, domain prefixes, and integration agreements all vary between teams.

No way to connect schema checks to internal compliance systems

Your organization may require API changes to be validated against an internal compliance system or governance tool. Standard linting has no hook for external systems.

Breaking changes reach production without team coordination

When a backend team removes or renames a field, the frontend teams who depend on it may not get coordinated notification before deployment. Generic validation does not cover custom team-notification workflows.

Our solution

A webhook that runs inside the check pipeline.

Subgraph Check Extensions send a POST request to your endpoint when a schema check runs in a namespace with extensions enabled. Your service receives the full picture of the proposed change, applies your logic, and returns findings that appear alongside Cosmo's built-in results. Errors can fail the check and block non-compliant changes before deployment.

How it works end to end

Configure a Subgraph Check Extension in Cosmo Studio at the namespace level, providing your endpoint URL and HMAC secret key.
When a schema check runs, Cosmo sends a POST request to your endpoint with the full check context — schema SDL, lint issues, schema changes, affected operations, and VCS metadata.
Your service validates the proposed changes against your rules. You can call external systems, query databases, or apply any logic in any language.
Return a 200 response with custom LintIssue objects that appear alongside built-in results, or include errors that explicitly fail the check. Return 204 to pass through with no issues.
Results appear in schema check results and CI/CD feedback. Errors can fail the check and block non-compliant changes before deployment.

Your rules. Your infrastructure. Enforced automatically.

Subgraph check extensions

Before & After

Before	With extensions
Generic linting rules that miss company-specific requirements	Custom validation enforcing exact organizational standards
No integration with internal compliance systems	Webhook-based integration with any external system
Breaking changes deployed without team coordination	Automated notifications to affected teams before deployment
Schema standards enforced through manual review	Automated enforcement with clear feedback in CI/CD

Payload context

What your endpoint receives

Schema SDL — Before and after versions of the proposed schema
Lint issues — Cosmo's built-in lint findings for the change
Schema changes — Detected additions, removals, and modifications
Affected operations — Client operations impacted by the change
VCS context — Branch, commit SHA, and author from source control
Download URL — Bulk data file URL — valid for 5 minutes

Key benefits

Your validation logic, inside the check pipeline

Available on Pro and Enterprise plans.

Unlimited custom validation

Write any validation logic in any language. Check naming conventions, enforce deprecation policies, validate against external systems, or implement custom business rules. Your endpoint, your logic.

Seamless CI/CD integration

Extensions run automatically during schema checks. Non-compliant changes can fail checks before they are merged or deployed, depending on your CI/CD policy — as part of the schema check workflow.

Full check context available

Receive schema SDL (before and after), built-in lint issues, detected schema changes, affected operations, and VCS metadata. A downloadable URL provides bulk data for 5 minutes.

Secure communication via HMAC

Requests from Cosmo include an HMAC-SHA256 signature in the X-Cosmo-Signature-256 header. Verify it with your secret key to confirm requests are genuine and unmodified.

Flexible response options

Return custom LintIssue objects with severity and precise line/column location, return errors that fail the check, or return 204 to pass through silently. You control whether to return lint issues, errors, or no additional findings.

How Subgraph Check Extensions work

01

Runs when extension enabled.

Schema check runs in your namespace

A developer proposes a schema change and the check pipeline starts. Cosmo detects that a Subgraph Check Extension is configured for the namespace.

02

Verify HMAC signature.

Cosmo sends a POST to your endpoint

Cosmo sends a POST request to your configured endpoint. The JSON payload contains organization context, namespace, subgraph details, VCS info, affected graphs, and a downloadable URL for bulk check data.

03

Any language, any system.

Your service validates the schema

Your endpoint receives the payload, verifies the HMAC signature, and applies your custom rules — checking naming conventions, calling external compliance systems, or notifying affected teams.

04

You control the severity.

You return issues, errors, or 204

Return 200 with LintIssue objects to surface findings alongside built-in checks, include errors to explicitly fail the check, or return 204 to pass through with no issues added.

05

Can fail check on errors.

Results appear in checks and CI/CD

Custom issues appear in the check results alongside Cosmo's built-in findings, in schema check results and CI/CD feedback. Non-compliant changes can fail checks before they are merged or deployed, depending on your CI/CD policy.

Use cases

When teams use Subgraph Check Extensions

Custom naming convention enforcement

Naming

Your company requires camelCase fields, PascalCase types, and domain-specific prefixes. The extension receives the schema SDL, validates naming patterns, and returns LintIssue objects with the rule type, severity, message, and the exact line and column of each violation.

Breaking change notifications

Coordination

When a backend team introduces a breaking change, frontend teams need to know before it ships. Enable 'Include Schema Changes' in the extension config. Your service analyzes the detected changes and sends notifications via Slack, email, or internal tools when breaking changes appear.

External compliance validation

Compliance

All API changes must pass your internal compliance system before reaching production. Your extension endpoint forwards the schema information to the compliance system, awaits the result, and translates failures into check errors that block deployment.

Deprecation policy enforcement

Deprecation

Your organization requires deprecated fields to remain available for a minimum period and deprecation reasons to include a sunset date in a specific format. The extension parses @deprecated directives from the SDL, validates the format, and checks against historical data for minimum deprecation periods.

When to use Subgraph Check Extensions

When to use

Your organization has schema standards that go beyond generic linting rules.
You need to connect schema validation to external compliance or approval systems.
You want to notify teams automatically when breaking changes are detected.
You want schema standards enforced in CI/CD with clear, actionable feedback.

Requirements

An HTTP endpoint accessible from Cosmo's control plane
A secret key for HMAC-SHA256 signature verification
Namespace-level configuration in Cosmo Studio
A Pro or Enterprise plan

Start enforcing your schema standards automatically

Subgraph Check Extensions are available on Pro and Enterprise plans.

Start on Pro See the docs

Ready to go deeper?

Full reference for payload structure, response format, HMAC verification, and a complete handler example.

Extension overview →Request payload structure →Response structure →Handler example →

Extend schema validation with your own logic.