What HTTP method does Cosmo use for webhook delivery?

Cosmo sends HTTP POST requests to your endpoint with a JSON body.

How do I verify a webhook payload is authentic?

Compute HMAC-SHA256 over the raw request body using the secret you configured, then compare it to the value in the X-Cosmo-Signature-256 header. A match means the payload came from Cosmo and was not modified in transit.

What event types are available?

The current event type is FEDERATED_GRAPH_SCHEMA_UPDATED, fired when a schema change updates the federated graph.

Can I have multiple webhooks for the same organization?

Yes. You can configure multiple webhooks per organization. Each has its own endpoint URL, secret, name, and event subscription. Different systems can receive independent notification streams.

What if my endpoint is temporarily unavailable?

Configure multiple webhooks as backup endpoints and implement retry logic in your receiving infrastructure for resilience.

Does my endpoint need to be publicly accessible?

Yes. Cosmo sends HTTP POST requests directly to your endpoint URL, so it must be reachable over the internet via HTTPS.

Webhook Notifications for Federated GraphQL | Cosmo by WunderGraph

Q: What does the webhook payload contain?

The versioned JSON payload (current version: 1) includes the federated graph ID, name, namespace, error status, and an optional actor_id identifying who triggered the event.

The problem

Reacting to schema changes requires events, not polls

CI/CD systems, documentation generators, and audit tools need to know when schemas change. Building the event delivery layer yourself takes longer than setting up the tool you actually want to integrate.

Polling APIs adds latency and maintenance burden

Checking for schema changes on a schedule means you always find out late. Polling code breaks when the API changes and adds another thing to monitor.

Building custom event infrastructure takes weeks

Capturing schema change events, routing them to the right systems, and maintaining that infrastructure is an engineering project in itself.

Generic webhooks carry no federation context

HTTP-level event systems can fire on a webhook, but the payload has no graph name, namespace, or error status. Your downstream system has to query Cosmo for the details.

Our solution

Event delivery to any HTTP endpoint

Cosmo pushes schema change events directly to your endpoint. Every request is signed. Every payload carries the context your downstream system needs. No polling, no custom event infrastructure to build.

From schema change to your system

Create a webhook in Cosmo Studio with your endpoint URL and a secret key.
Subscribe the webhook to the FEDERATED_GRAPH_SCHEMA_UPDATED event.
When that event occurs, Cosmo sends an HTTP POST request to your endpoint.
The request includes an X-Cosmo-Signature-256 header with an HMAC-SHA256 signature computed from your secret.
Verify the signature in your endpoint before processing. The JSON payload carries the graph ID, name, namespace, error status, and actor_id.
Your system reacts: trigger CI/CD, update documentation, log to an audit system, or do anything an HTTP endpoint can do.

One configuration. Any system that speaks HTTP.

Webhook Notifications

Before & After

Before Cosmo	With Cosmo
Polling the schema registry for changes	Real-time push notification the moment the schema updates
Building custom event infrastructure	Out-of-the-box webhook system, ready in minutes
No way to verify event authenticity	HMAC-SHA256 signature on every request
Single integration point for all downstream systems	Multiple webhooks per organization, each independently configured

Signature verification

Verify with standard HMAC-SHA256

import crypto from 'crypto';

function verifySignature(body, receivedSignature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return computedSignature === receivedSignature;
}

// Usage:
const isVerified = verifySignature(
  JSON.stringify(req.body),
  req.headers['x-cosmo-signature-256'],
  YOUR_SECRET
);

How webhook notifications work in Cosmo

01

One config. Any HTTP endpoint.

Configure

Create a webhook in Cosmo Studio. Provide your endpoint URL, a secret key for signature verification, and select the event types to subscribe to.

02

Sub-second delivery.

Receive

When a subscribed event occurs, Cosmo sends an HTTP POST request to your endpoint with a versioned JSON payload. Delivery is sub-second.

03

HMAC-SHA256. Standard crypto.

Verify

Check the X-Cosmo-Signature-256 header. Compute HMAC-SHA256 over the raw request body using your secret. If the signatures match, the payload is authentic.

04

CI/CD, audit, docs, anything.

React

Parse the payload: federated graph ID, name, namespace, error status, and actor_id. Trigger CI/CD, write to an audit log, regenerate docs, or route to any downstream system.

What's included

Webhook delivery and verification

Standard HTTP POST, standard HMAC-SHA256, versioned payloads.

HMAC-SHA256 signatures

Every request includes X-Cosmo-Signature-256. Compute the same signature with your secret and compare. Mismatches mean reject.

Versioned JSON payloads

Payloads are versioned (current: v1) and carry the federated graph ID, name, namespace, error status, and actor_id. Consistent schema, predictable parsing.

Unlimited webhooks per organization

Configure as many webhooks as you need. Each has its own name, endpoint, secret, and event subscription. Different systems receive independent event streams.

Works with existing infrastructure

CI/CD systems (GitHub Actions, GitLab CI, Jenkins), monitoring platforms (Datadog, PagerDuty), documentation generators, and audit systems all work out of the box. Any system that accepts HTTP POST works.

Connect schema changes to your systems

Add a webhook endpoint in Cosmo Studio. Events start flowing to your CI/CD, audit log, or monitoring system immediately.

Start Free Read the Docs

Receive federated graph events at any HTTP endpoint