{ "openapi": "3.1.0", "info": { "title": "Plus API", "version": "1.1.0", "description": "Customer-authorized Plus recharge; API Key + BYO Session/card. Public contract only. HTTP success is not payment success. v1.1 adds asynchronous error_code, next_action and evidence fields without changing status/result_code. See /docs for exact retry and safety rules." }, "servers": [ { "url": "https://api.666666.homes" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "summary": "查询账户与积分", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/cards": { "get": { "operationId": "listPrivateCards", "summary": "当前 API Key 私人卡池（仅脱敏信息）", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateCard" } } }, "required": [ "cards" ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/cards/import": { "post": { "operationId": "importPrivateCards", "summary": "导入自己的银行卡（不自动开卡）", "description": "Duplicate PAN within this Key is unchanged, including usage and limits. No platform/other-Key cards.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "duplicates": { "type": "integer" } }, "required": [ "added", "duplicates" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardImport" } } } } } }, "/v1/cards/{card_id}": { "post": { "operationId": "updatePrivateCard", "summary": "调整次数、暂停或删除私人卡", "description": "Requires current version. Occupied/unknown cards cannot be changed. Deleting does not reset historical successes.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdate" } } } }, "parameters": [ { "name": "card_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/credits/redeem": { "post": { "operationId": "redeemCredits", "summary": "兑换积分卡密", "description": "Repeat by same customer does not credit twice.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemResult" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemRequest" } } } } } }, "/v1/credits/ledger": { "get": { "operationId": "getCreditLedger", "summary": "积分流水（每页最多50条）", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } } }, "required": [ "entries" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Last ID from previous page; omit on first page." } ] } }, "/v1/preflights": { "post": { "operationId": "createPreflight", "summary": "提前预检（不授权付款）", "description": "120 seconds from creation; use expires_at. Requires available >= 1, no freeze yet. Same request_id and content returns original preflight.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preflight" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightRequest" } } } } } }, "/v1/preflights/{preflight_id}": { "get": { "operationId": "getPreflight", "summary": "查询预检", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preflight" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "preflight_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/orders": { "post": { "operationId": "submitOrder", "summary": "用户明确确认后提交", "description": "Freezes 1 credit. Never submit without consent. Same request_id and parameters is idempotent. Response loss is not failure.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } } }, "get": { "operationId": "listOrders", "summary": "最近50条订单（无分页）", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } }, "required": [ "orders" ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{order_id}": { "get": { "operationId": "getOrder", "summary": "查询订单与进度", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/orders/{order_id}/invoice": { "get": { "operationId": "getInvoice", "summary": "获取账单跳转", "description": "", "responses": { "303": { "description": "Open/download Location in a new request WITHOUT API Authorization.", "headers": { "Location": { "required": true, "schema": { "type": "string", "format": "uri" } } } }, "404": { "description": "invoice_not_ready; does not change recharge success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhook": { "get": { "operationId": "getWebhook", "summary": "读取回调配置（不返回密钥）", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "setWebhook", "summary": "设置回调（每次轮换密钥）", "description": "Not idempotent: save rotates signing secret/generation. Do not blindly retry after timeout.", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSaved" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } } } }, "delete": { "operationId": "disableWebhook", "summary": "关闭回调", "description": "", "responses": { "200": { "description": "Request accepted; inspect business status, not HTTP alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Service API Key, not Session or payment-platform key." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "balance": { "type": "integer", "minimum": 0 }, "frozen": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 32 } }, "required": [ "id", "name", "balance", "frozen", "available", "concurrency" ] }, "RedeemRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 10, "maxLength": 128 } }, "required": [ "code" ], "additionalProperties": false }, "RedeemResult": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 1 }, "already_redeemed": { "type": "boolean" } }, "required": [ "credits", "already_redeemed" ] }, "Card": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^\\d{12,19}$", "description": "Digits only; checksum must pass." }, "exp_month": { "type": "string", "pattern": "^(0?[1-9]|1[0-2])$" }, "exp_year": { "type": "string", "pattern": "^20\\d{2}$" }, "cvc": { "type": "string", "pattern": "^\\d{3,4}$" } }, "required": [ "number", "exp_month", "exp_year", "cvc" ], "additionalProperties": false }, "PreflightRequest": { "type": "object", "properties": { "request_id": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "session": { "type": "string", "description": "Complete authorized Session JSON encoded as a string; 20–65536 UTF-8 bytes. Never log it." }, "card": { "$ref": "#/components/schemas/Card" }, "card_id": { "type": "string", "pattern": "^pcard_[a-f0-9]{32}$", "description": "Only a card under this exact API Key; omit both card and card_id to select from its private pool." } }, "required": [ "request_id", "session" ], "additionalProperties": false, "not": { "required": [ "card", "card_id" ] } }, "PrivateCard": { "type": "object", "properties": { "id": { "type": "string" }, "last4": { "type": "string" }, "expiry": { "type": "string" }, "use_limit": { "type": "integer" }, "success_count": { "type": "integer" }, "version": { "type": "integer" }, "remaining": { "type": "integer" }, "status": { "type": "string", "enum": [ "available", "occupied", "paused", "expired", "exhausted" ] } }, "required": [ "id", "last4", "expiry", "use_limit", "success_count", "version", "remaining", "status" ] }, "CardImport": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 32768, "description": "One card per line, at most 100: PAN MM/YYYY CVC or PAN----MM----YYYY----CVC. Never log." }, "use_limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 5 } }, "required": [ "text" ], "additionalProperties": false }, "CardUpdate": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "use_limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "enabled": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "version" ], "additionalProperties": false }, "Preflight": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "number" }, "expires_at": { "type": "number" }, "order_id": { "type": "string", "description": "Empty before submission; otherwise query this original order. Linked-order state is authoritative." }, "status": { "type": "string", "enum": [ "queued", "preparing", "ready", "adopted", "cleanup_pending", "closed", "failed", "expired" ] }, "credit_state": { "type": "string", "enum": [ "none", "frozen", "consumed", "released", "unknown" ], "description": "none without an order; otherwise the associated order service-credit state. unknown if the linked order cannot be read." }, "error_code": { "type": "string", "enum": [ "", "SESSION_INVALID", "GRACE_SESSION_REFRESH_REQUIRED", "GRACE_CANCEL_REQUIRED", "WEB_RENEWAL_CANCEL_UNVERIFIED", "SUBSCRIPTION_NOT_EXPIRED", "UNSUPPORTED_CHANNEL", "PREFLIGHT_TECHNICAL_ERROR", "CHECKOUT_CREATE_RESPONSE_LOST", "PREFLIGHT_EXPIRED", "PREFLIGHT_FAILED", "PREFLIGHT_CLOSED", "PREFLIGHT_CLEANUP_PENDING", "PAYMENT_FAILED", "PAYMENT_UNCONFIRMED" ], "description": "Stable asynchronous business code; empty for no error. Request errors use error.code instead. Accept future codes." }, "customer_message": { "type": "string", "description": "Safe customer display text; do not match text to decide behavior." }, "stage": { "type": "string", "description": "Public progress/failure stage, such as preflight, session_validating, subscription_check, checkout_creating, stripe_artifacts, cleanup, payment or reconciliation; accept new stages." }, "retryable": { "type": "boolean", "description": "Whether the indicated business action may be retried now. Never permission to replay a payment confirmation." }, "next_action": { "type": "string", "enum": [ "renew_session", "cancel_renewal_and_renew_session", "wait_subscription_expiry", "change_channel", "retry_preflight", "wait_cleanup", "wait_result", "submit_order", "none", "wait", "contact_support" ], "description": "Follow together with status, cleanup_acknowledged and order_id. Never authorizes payment without customer confirmation." }, "cleanup_acknowledged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "true: cleanup acknowledged; false: pending; null: no reliable cleanup conclusion." }, "payment_started": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Entered payment processing; true is not payment success. null is unknown, not false." }, "card_consumed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "This service has recorded this order as a successful card use. Not service credits, remaining uses, issuer balance or a bank transaction lookup. Unknown is null." } }, "required": [ "id", "created_at", "expires_at", "order_id", "status", "credit_state", "error_code", "customer_message", "stage", "retryable", "next_action", "cleanup_acknowledged", "payment_started", "card_consumed" ] }, "OrderRequest": { "type": "object", "properties": { "request_id": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "preflight_id": { "type": "string" }, "confirmed": { "type": "boolean", "const": true }, "allow_fallback": { "type": "boolean", "default": false } }, "required": [ "request_id", "preflight_id", "confirmed" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "description": "Progress event, not payment proof." }, "created_at": { "type": "number" } }, "required": [ "id", "kind", "created_at" ] }, "LedgerEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "redeem", "freeze", "consume", "release" ] }, "reference": { "type": "string" }, "balance_delta": { "type": "integer" }, "frozen_delta": { "type": "integer" }, "balance_after": { "type": "integer" }, "frozen_after": { "type": "integer" }, "created_at": { "type": "number" } }, "required": [ "id", "kind", "reference", "balance_delta", "frozen_delta", "balance_after", "frozen_after", "created_at" ] }, "WebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL, port 443, no userinfo or fragment." } }, "required": [ "url" ], "additionalProperties": false }, "WebhookSaved": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean", "const": true }, "signing_secret": { "type": "string", "description": "Shown only by this save; another POST rotates it." }, "generation": { "type": "integer" } }, "required": [ "url", "enabled", "signing_secret", "generation" ] }, "WebhookConfig": { "oneOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "const": false } }, "required": [ "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "oneOf": [ { "type": "boolean" }, { "type": "integer", "enum": [ 0, 1 ] } ] }, "generation": { "type": "integer" } }, "required": [ "url", "enabled", "generation" ] } ] }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "request_id": { "type": "string" }, "preflight_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "preparing", "paying", "review", "succeeded", "failed" ] }, "credit_state": { "type": "string", "enum": [ "frozen", "consumed", "released" ] }, "created_at": { "type": "number" }, "started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "success_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated_at": { "type": "number" }, "result_code": { "type": "string", "enum": [ "", "PAYMENT_FAILED", "PAYMENT_UNCONFIRMED" ], "description": "Legacy broad classification is preserved. Use error_code for a detailed asynchronous cause." }, "error_code": { "type": "string", "enum": [ "", "SESSION_INVALID", "GRACE_SESSION_REFRESH_REQUIRED", "GRACE_CANCEL_REQUIRED", "WEB_RENEWAL_CANCEL_UNVERIFIED", "SUBSCRIPTION_NOT_EXPIRED", "UNSUPPORTED_CHANNEL", "PREFLIGHT_TECHNICAL_ERROR", "CHECKOUT_CREATE_RESPONSE_LOST", "PREFLIGHT_EXPIRED", "PREFLIGHT_FAILED", "PREFLIGHT_CLOSED", "PREFLIGHT_CLEANUP_PENDING", "PAYMENT_FAILED", "PAYMENT_UNCONFIRMED" ], "description": "Stable asynchronous business code; empty for no error. Request errors use error.code instead. Accept future codes." }, "customer_message": { "type": "string", "description": "Safe customer display text; do not match text to decide behavior." }, "stage": { "type": "string", "description": "Public progress/failure stage, such as preflight, session_validating, subscription_check, checkout_creating, stripe_artifacts, cleanup, payment or reconciliation; accept new stages." }, "retryable": { "type": "boolean", "description": "Whether the indicated business action may be retried now. Never permission to replay a payment confirmation." }, "next_action": { "type": "string", "enum": [ "renew_session", "cancel_renewal_and_renew_session", "wait_subscription_expiry", "change_channel", "retry_preflight", "wait_cleanup", "wait_result", "submit_order", "none", "wait", "contact_support" ], "description": "Follow together with status, cleanup_acknowledged and order_id. Never authorizes payment without customer confirmation." }, "cleanup_acknowledged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "true: cleanup acknowledged; false: pending; null: no reliable cleanup conclusion." }, "payment_started": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Entered payment processing; true is not payment success. null is unknown, not false." }, "card_consumed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "This service has recorded this order as a successful card use. Not service credits, remaining uses, issuer balance or a bank transaction lookup. Unknown is null." } }, "required": [ "id", "request_id", "preflight_id", "status", "credit_state", "created_at", "started_at", "payment_at", "success_at", "finished_at", "updated_at", "result_code", "error_code", "customer_message", "stage", "retryable", "next_action", "cleanup_acknowledged", "payment_started", "card_consumed" ] }, "OrderDetail": { "type": "object", "properties": { "id": { "type": "string" }, "request_id": { "type": "string" }, "preflight_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "preparing", "paying", "review", "succeeded", "failed" ] }, "credit_state": { "type": "string", "enum": [ "frozen", "consumed", "released" ] }, "created_at": { "type": "number" }, "started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "success_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated_at": { "type": "number" }, "result_code": { "type": "string", "enum": [ "", "PAYMENT_FAILED", "PAYMENT_UNCONFIRMED" ], "description": "Legacy broad classification is preserved. Use error_code for a detailed asynchronous cause." }, "error_code": { "type": "string", "enum": [ "", "SESSION_INVALID", "GRACE_SESSION_REFRESH_REQUIRED", "GRACE_CANCEL_REQUIRED", "WEB_RENEWAL_CANCEL_UNVERIFIED", "SUBSCRIPTION_NOT_EXPIRED", "UNSUPPORTED_CHANNEL", "PREFLIGHT_TECHNICAL_ERROR", "CHECKOUT_CREATE_RESPONSE_LOST", "PREFLIGHT_EXPIRED", "PREFLIGHT_FAILED", "PREFLIGHT_CLOSED", "PREFLIGHT_CLEANUP_PENDING", "PAYMENT_FAILED", "PAYMENT_UNCONFIRMED" ], "description": "Stable asynchronous business code; empty for no error. Request errors use error.code instead. Accept future codes." }, "customer_message": { "type": "string", "description": "Safe customer display text; do not match text to decide behavior." }, "stage": { "type": "string", "description": "Public progress/failure stage, such as preflight, session_validating, subscription_check, checkout_creating, stripe_artifacts, cleanup, payment or reconciliation; accept new stages." }, "retryable": { "type": "boolean", "description": "Whether the indicated business action may be retried now. Never permission to replay a payment confirmation." }, "next_action": { "type": "string", "enum": [ "renew_session", "cancel_renewal_and_renew_session", "wait_subscription_expiry", "change_channel", "retry_preflight", "wait_cleanup", "wait_result", "submit_order", "none", "wait", "contact_support" ], "description": "Follow together with status, cleanup_acknowledged and order_id. Never authorizes payment without customer confirmation." }, "cleanup_acknowledged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "true: cleanup acknowledged; false: pending; null: no reliable cleanup conclusion." }, "payment_started": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Entered payment processing; true is not payment success. null is unknown, not false." }, "card_consumed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "This service has recorded this order as a successful card use. Not service credits, remaining uses, issuer balance or a bank transaction lookup. Unknown is null." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "required": [ "id", "request_id", "preflight_id", "status", "credit_state", "created_at", "started_at", "payment_at", "success_at", "finished_at", "updated_at", "result_code", "error_code", "customer_message", "stage", "retryable", "next_action", "cleanup_acknowledged", "payment_started", "card_consumed", "events" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "order.updated" }, "created_at": { "type": "number" }, "data": { "$ref": "#/components/schemas/Order" } }, "required": [ "id", "type", "created_at", "data" ] } }, "responses": { "Error": { "description": "Request error; never infer payment failure from a transport/API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "webhooks": { "orderUpdated": { "post": { "summary": "Order progress / result / invoice-ready notification", "description": "HMAC-SHA256(secret, timestamp + dot + raw body); at most 8 attempts. Dedupe X-Event-Id and protect succeeded against stale events. Old queued notifications may predate additive error fields; GET the original order for current data.", "parameters": [ { "in": "header", "name": "X-Event-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Webhook-Timestamp", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Persist event and acknowledge quickly (delivery timeout ~5s)." } } } } } }