Run Hermes as a WeCom Callback Self-Built App

WeCom Callback runs Hermes as a self-built enterprise application. Unlike the simpler WebSocket bot mode, it receives signed, AES-encrypted XML at a public HTTPS endpoint, acknowledges quickly, and later sends the completed answer through WeCom's proactive message API.

Choose callback mode deliberately

Use this mode when Hermes should appear as a first-class app in the WeCom sidebar or when one gateway must route several corporate applications. Use the WebSocket bot path when group-chat convenience and a simpler network setup matter more.

Create the app in WeCom's admin console, collect the Corp ID, application secret, Agent ID, callback token, and EncodingAESKey, then run hermes gateway setup. The callback URL must be publicly reachable over HTTPS. Keep the listener behind a trusted reverse proxy or tunnel and restrict source networks when exposing it directly.

Setup checklist

Create a WeCom self-built application.
Configure a public HTTPS callback URL.
Store the callback token and AES key as secrets.
Restrict allowed users or explicitly approve open access.
Keep the initial callback acknowledgment fast.
Scope multi-app users by corporation and user ID.

Pitfalls

A reachable endpoint can still fail verification when the callback token or EncodingAESKey is truncated. Binding only to loopback requires a reverse proxy or tunnel. Callback mode does not stream or show typing indicators, so users receive the final reply after processing. Current inbound support is text-first; do not promise image, file, or voice ingestion without testing the live adapter version.

Verification steps

Complete WeCom's GET callback verification.
Send a text message and confirm the POST is signature-validated and decrypted.
Verify Hermes acknowledges promptly and sends exactly one proactive reply.
Test an unauthorized user and confirm denial.
For multi-app setups, send from two corporations and verify replies use the correct app token.
Probe the health endpoint through the same public routing layer.

Read the official WeCom Callback guide for configuration keys, encryption behavior, routing, and limitations.