Credential callback protocol

Receive verification requests or events from external platforms, resolve saved channel credentials by credential reference, and enter callback rules. This differs from ingress for a specified message connection.

Path and identity

GET https://api.moi.matrixorigin.cn/v5/callbacks/{provider}/{workspace_id}/{credential_ref}
POST /callbacks/{provider}/{workspace_id}/{credential_ref}

Paths come from deployment and channel-instance configuration. credential_ref is a credential reference, not connection_id, a PAT, or a public Web application token. The handler has no product identity wrapper, but the service still validates credential workspace, platform/tool bindings, active status, expiration, and platform protocol credentials.

Do not add regular product SDK methods to call these two callback receiver paths. Configured external platforms are the callers. Users configure them through existing instance, credential, and callback-rule management capabilities.

GET verification

GET currently supports WeCom only. It reads timestamp, nonce, echostr, signature, and msg_signature, verifies the challenge using saved callback Token/encryption settings, and returns the platform’s raw response. A provider path parameter does not imply every platform supports GET verification.

A successful challenge proves only that verification passed, not that a rule matched, an agent task executed, or a reply reached the platform.

POST events

Event branches include WeCom, GitHub, Lark, Slack, and Telegram, each using its platform credentials and message protocol. GitHub verifies the signed raw body and identifies event/delivery IDs. Slack signature validation includes a time window. Other platforms have their own challenge, encryption, and secret constraints. A regular PAT is not a substitute.

Authenticated events enter callback rules and corresponding targets. Platform HTTP acknowledgments may be plain text or platform JSON, not a fixed code=OK envelope. Unmatched events and challenges may be acknowledged without triggering a task. smart-bot credentials are rejected by the legacy event-sink path; do not conflate it with the WeCom smart-bot ingress branch.

Size and errors

This POST handler reads4 MiB plus one byte to detect overflow; oversized input returns 400/code 2. This differs from message ingress’s2 MiB limit and413 result, so there is no common callback size guarantee. Gateways may impose further limits; actual environments need verification.

Errors use numeric code, message, and details potentially containing request_id. Handle parameter400/2, signature/decryption401/6, missing credential404/3, not-ready424/15, and missing event-sink configuration503/15 separately. Some general messages still say wecom; do not infer the requested platform from the text. Complete platform error, replay, and rule-execution lifecycles require further verification.

Last updated on