Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#852 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
graphql, openapi
Lĩnh vực
api, documentation

Hướng nghiên cứu

Bắt đầu bằng cách xác định đặc tả OpenAPI hiện có của Notify API và xem xét cách các component của nó được tổ chức. Định nghĩa các component chính thức cho webhook envelope và event body của Address Activity và NFT Activity, sau đó cung cấp schema GraphQL của Custom Webhooks dưới dạng SDL, JSON introspection hoặc một public endpoint. Được xem là hoàn tất khi consumer có thể sinh type và xác thực payload cũng như query, đồng thời mối quan hệ giữa kết quả GraphQL và webhook event được tài liệu hóa.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
MDX
Star
8
Fork
18
Merge trung bình
21 giờ 8 phút
Pull request đã merge (30 ngày)
45

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của alchemyplatform/docs

Tất cả issue của alchemyplatform/docs

Issue tương tự

Thêm issue về Backend & API Design

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.