{
  "openapi": "3.1.0",
  "info": {
    "title": "Cloudsign Webhook receiver contract",
    "version": "1.3.0-preview.1",
    "description": "接收端按 CSWH1 验签原始字节，时间偏差最多 300 秒。验证请求须回显 event_id、challenge 和 CSWH1-ACK 密钥证明；普通通知回显 event_id。接收端必须持久去重。 财务通知仅对新订阅且单独获授权的 API 应用发送，回执与事件须持久去重；不保证事件顺序。只提供原始交易的公开标识和金额，不提供余额。自定义金额单位使用 currency_revision 绑定原报价，按原购买报价确认展示单位。 新增原 API 应用的 version.ready（已校验原包）与 distribution.published（自动发布或历史版本切换）；独立订阅权限，不补发订阅前活动。事件可能乱序或重复，查询版本列表确认当前发布版本。 来源由接收端绑定的订阅 WHK 区分：api、website（历史发布）和 website_upload（已有普通分发应用的现代网站更新上传）。后两项独立审批、显式订阅、默认关闭。网站更新上传的 version.ready 中 U 关联真实网站直传任务，不是 API 上传会话，不能用于 API 的上传查询、恢复或取消；用 A / V 读取版本状态。不同来源不会自动互相广播；首次新建、旧式 S3、企业及超级签名网站上传尚未覆盖。"
  },
  "webhooks": {
    "notification": {
      "post": {
        "operationId": "receiveCloudsignNotification",
        "parameters": [
          {
            "name": "X-Cloudsign-Webhook-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^WHK[a-f0-9]{40}$"
            }
          },
          {
            "name": "X-Cloudsign-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^E[a-f0-9]{32}$"
            }
          },
          {
            "name": "X-Cloudsign-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{8,11}$"
            }
          },
          {
            "name": "X-Cloudsign-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^v1=[a-f0-9]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Notification"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "必须在完成验签及幂等登记后确认接收；验证请求还须证明持有回调密钥",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Receipt"
                    },
                    {
                      "$ref": "#/components/schemas/ChallengeReceipt"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "报文或签名无效；平台按有界策略重试"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "signing_succeeded": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "signing.succeeded"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^J[a-f0-9]{32}$"
              },
              "status": {
                "const": "succeeded"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "signing_failed": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "signing.failed"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^J[a-f0-9]{32}$"
              },
              "status": {
                "const": "failed"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "signing_cancelled": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "signing.cancelled"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^J[a-f0-9]{32}$"
              },
              "status": {
                "const": "cancelled"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "signing_superseded": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "signing.superseded"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^J[a-f0-9]{32}$"
              },
              "status": {
                "const": "superseded"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "upload_completed": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "upload.completed"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^U[a-f0-9]{32}$"
              },
              "status": {
                "const": "succeeded"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "upload_failed": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "upload.failed"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^U[a-f0-9]{32}$"
              },
              "status": {
                "const": "failed"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "upload_cancelled": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "upload.cancelled"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^U[a-f0-9]{32}$"
              },
              "status": {
                "const": "cancelled"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "endpoint_challenge": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "endpoint.challenge"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "challenge": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            },
            "required": [
              "challenge"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "Notification": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/signing_succeeded"
          },
          {
            "$ref": "#/components/schemas/signing_failed"
          },
          {
            "$ref": "#/components/schemas/signing_cancelled"
          },
          {
            "$ref": "#/components/schemas/signing_superseded"
          },
          {
            "$ref": "#/components/schemas/upload_completed"
          },
          {
            "$ref": "#/components/schemas/upload_failed"
          },
          {
            "$ref": "#/components/schemas/upload_cancelled"
          },
          {
            "$ref": "#/components/schemas/endpoint_challenge"
          },
          {
            "$ref": "#/components/schemas/order_paid"
          },
          {
            "$ref": "#/components/schemas/refund_completed"
          },
          {
            "$ref": "#/components/schemas/capacity_purchased"
          },
          {
            "$ref": "#/components/schemas/version_ready"
          },
          {
            "$ref": "#/components/schemas/distribution_published"
          }
        ]
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          }
        },
        "required": [
          "event_id"
        ],
        "additionalProperties": false
      },
      "ChallengeReceipt": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "challenge": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "proof": {
            "type": "string",
            "pattern": "^v1=[a-f0-9]{64}$"
          }
        },
        "required": [
          "event_id",
          "challenge",
          "proof"
        ],
        "additionalProperties": false
      },
      "order_paid": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "order.paid"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^O[a-f0-9]{32}$"
              },
              "quote_id": {
                "type": "string",
                "pattern": "^Q[a-f0-9]{32}$"
              },
              "status": {
                "const": "paid"
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
              },
              "currency_code": {
                "type": "string",
                "enum": [
                  "CNY",
                  "USD",
                  "EUR",
                  "HKD",
                  "GBP",
                  "POINT",
                  "CUSTOM"
                ]
              },
              "currency_revision": {
                "type": "string",
                "pattern": "^C[a-f0-9]{64}$"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "quote_id",
              "status",
              "amount",
              "currency_code",
              "currency_revision"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "refund_completed": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "refund.completed"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^O[a-f0-9]{32}$"
              },
              "quote_id": {
                "type": "string",
                "pattern": "^Q[a-f0-9]{32}$"
              },
              "status": {
                "const": "refunded"
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
              },
              "currency_code": {
                "type": "string",
                "enum": [
                  "CNY",
                  "USD",
                  "EUR",
                  "HKD",
                  "GBP",
                  "POINT",
                  "CUSTOM"
                ]
              },
              "currency_revision": {
                "type": "string",
                "pattern": "^C[a-f0-9]{64}$"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "quote_id",
              "status",
              "amount",
              "currency_code",
              "currency_revision"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "capacity_purchased": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "capacity.purchased"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^O[a-f0-9]{32}$"
              },
              "quote_id": {
                "type": "string",
                "pattern": "^Q[a-f0-9]{32}$"
              },
              "status": {
                "const": "paid"
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
              },
              "currency_code": {
                "type": "string",
                "enum": [
                  "CNY",
                  "USD",
                  "EUR",
                  "HKD",
                  "GBP",
                  "POINT",
                  "CUSTOM"
                ]
              },
              "currency_revision": {
                "type": "string",
                "pattern": "^C[a-f0-9]{64}$"
              }
            },
            "required": [
              "app_id",
              "resource_id",
              "quote_id",
              "status",
              "amount",
              "currency_code",
              "currency_revision"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "version_ready": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "version.ready"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "app_id",
              "resource_id",
              "status",
              "upload_id"
            ],
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^V[a-f0-9]{32}$"
              },
              "status": {
                "type": "string",
                "const": "ready"
              },
              "upload_id": {
                "type": "string",
                "pattern": "^U[a-f0-9]{32}$"
              }
            }
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      },
      "distribution_published": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "pattern": "^E[a-f0-9]{32}$"
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^WHK[a-f0-9]{40}$"
          },
          "type": {
            "const": "distribution.published"
          },
          "created_at": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "app_id",
              "resource_id",
              "status",
              "previous_version_id"
            ],
            "properties": {
              "app_id": {
                "type": "string",
                "pattern": "^A[a-f0-9]{32}$"
              },
              "resource_id": {
                "type": "string",
                "pattern": "^V[a-f0-9]{32}$"
              },
              "status": {
                "type": "string",
                "const": "published"
              },
              "previous_version_id": {
                "oneOf": [
                  {
                    "type": "string",
                    "pattern": "^V[a-f0-9]{32}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        },
        "required": [
          "schema_version",
          "id",
          "webhook_id",
          "type",
          "created_at",
          "data"
        ],
        "additionalProperties": false
      }
    }
  },
  "x-cloudsign-signature": {
    "request_canonical": [
      "CSWH1",
      "webhook_id",
      "event_id",
      "timestamp",
      "sha256(raw_body)"
    ],
    "challenge_ack_canonical": [
      "CSWH1-ACK",
      "webhook_id",
      "event_id",
      "challenge"
    ],
    "algorithm": "HMAC-SHA256; v1=<lowercase hex>",
    "max_body_bytes": 8192,
    "max_clock_skew_seconds": 300
  }
}
