WeCom Callback (Self-Built App)

Connect Hermes to WeCom (Enterprise WeChat) as a self-built enterprise application using the callback/webhook model.

See also: WeCom Bot for the bot-style integration.

Run hermes gateway setup and pick WeCom Callback for a guided walk-through.

1. You register a self-built application in the WeCom Admin Console
2. WeCom pushes encrypted XML to your HTTP callback endpoint
3. Hermes decrypts the message, queues it for the agent
4. Immediately acknowledges (silent — nothing displayed to the user)
5. The agent processes the request (typically 3–30 minutes)
6. The reply is delivered proactively via the WeCom message/send API

• A WeCom enterprise account with admin access
• aiohttp and httpx Python packages (included in the default install)
• A publicly reachable server for the callback URL (or a tunnel like ngrok)

1. Create a Self-Built App in WeCom

1. Go to WeCom Admin Console ↗ → Applications → Create App
2. Note your Corp ID (shown at the top of the admin console)
3. In the app settings, create a Corp Secret
4. Note the Agent ID from the app's overview page
5. Under Receive Messages, configure the callback URL:
6. URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
7. Token: Generate a random token (WeCom provides one)
8. EncodingAESKey: Generate a key (WeCom provides one)

2. Configure Environment Variables

Add to your .env file:

WECOM_CALLBACK_CORP_ID=your-corp-id
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key

# Optional
# WECOM_CALLBACK_HOST=  # optional pin; unset = dual-stack (all interfaces, IPv4+IPv6)
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. Start the Gateway

hermes gateway

(Use hermes gateway start only after hermes gateway install has registered the systemd/launchd service.)

The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.

Set these in config.yaml under platforms.wecom_callback.extra, or use environment variables:

For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the apps list in config.yaml:

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."
        - name: "dept-b"
          corp_id: "ww_corp_b"
          corp_secret: "secret-b"
          agent_id: "1000003"
          token: "token-b"
          encoding_aes_key: "key-b-43-chars..."

Users are scoped by corp_id:user_id to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app's access token.

Restrict which users can interact with the app:

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

The adapter exposes:

All callback payloads are encrypted with AES-CBC using the EncodingAESKey. The adapter handles:

• Inbound: Decrypt XML payload, verify SHA1 signature
• Outbound: Replies sent via proactive API (not encrypted callback response)

The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SDK.

• No streaming — replies arrive as complete messages after the agent finishes
• No typing indicators — the callback model doesn't support typing status
• Text only — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
• Response latency — agent sessions take 3–30 minutes; users see the reply when processing completes

Signature verification failing. WeCom signs every request with the Token you registered in the admin console. A mismatch between the token configured in Hermes and the token the admin console expects is the most common cause. Re-copy both the Token and EncodingAESKey from the admin console — they're easy to truncate. Whitespace in ~/.hermes/.env values around = will also break signature checks. After fixing, restart hermes gateway run.

Callback URL not reachable / verification step fails. WeCom hits the public URL you registered. Confirm:

1. Your reverse proxy / tunnel forwards /wecom/callback to the gateway's port.
2. The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
3. From outside your network, curl -i https://<your-domain>/wecom/callback returns something other than a timeout (a 4xx without query params is fine — it just means the listener is reachable).

Port not reachable / listener not bound. Check hermes gateway run logs for the bound host/port. If the adapter bound to 127.0.0.1 you must front it with a reverse proxy or tunnel — WeCom's servers can't reach loopback. Leave extra.host unset so the default dual-stack bind (all interfaces, IPv4+IPv6) applies, or pin an interface in config.yaml (plus allowed_source_cidrs if exposing directly) or keep loopback and use a tunnel such as Cloudflare Tunnel / nginx.