Request: Public schema for Notify webhook payloads and Custom Webhook GraphQL

[winor30]

Summary

Notify has an OpenAPI spec for managing webhooks, but there is no official, machine-readable schema for:

• The webhook payloads actually sent to our endpoints
• The GraphQL schema used by Custom Webhooks

Having these as official schemas would make it much easier to build and validate strongly typed integrations.

Request 1: Schemas for webhook payloads

Provide OpenAPI components for webhook event bodies, especially:

• Address Activity Webhook
• NFT Activity Webhook

Suggested scope:

• Top-level envelope
  • webhookId, id, createdAt, type, event, etc.
• event object
  • network as an enum (aligned with the existing Notify API OpenAPI)
  • activity[] items with clear required/optional fields, types, and nullability
• Enum-like fields
  • For example: category values such as external, internal, erc20, erc721, erc1155, token, etc.

These should be provided as OpenAPI components alongside the existing Notify API spec.

Request 2: Schema for Custom Webhooks GraphQL

Provide a way to consume the Custom Webhooks GraphQL schema, for example:

• SDL file (schema.graphql), or
• Introspection JSON, or
• A public endpoint with introspection enabled (even read-only / rate-limited)

This would allow:

• GraphQL code generation (TypeScript, Go, etc.)
• IDE autocomplete and static validation for Custom Webhook queries
• CI validation of GraphQL queries against the real schema

It would also help to document how the GraphQL result is embedded in the webhook payload (relationship between GraphQL data and the event object / top-level envelope).

Motivation

• We validate incoming webhook requests using JSON Schema / OpenAPI at the edge.
• We use schema/codegen to generate types for multiple services from a single source of truth.
• Without official schemas, we have to rely on prose docs and examples, which is fragile when payloads or fields evolve.