WeCom Callback(Self-Built App)

callback/webhook model을 사용해 Hermes를 self-built enterprise application 형태의 WeCom(Enterprise WeChat)에 연결합니다.

WeCom Bot vs WeCom Callback

Hermes는 두 가지 WeCom integration mode를 지원합니다.

• WeCom Bot - bot-style이며 WebSocket으로 연결됩니다. 설정이 더 단순하고 group chat에서 동작합니다.
• WeCom Callback(이 페이지) - self-built app이며 encrypted XML callback을 받습니다. 사용자의 WeCom sidebar에 first-class app으로 표시됩니다. multi-corp routing을 지원합니다.

동작 방식

1. WeCom Admin Console에서 self-built application을 등록합니다.
2. WeCom이 encrypted XML을 HTTP callback endpoint로 push합니다.
3. Hermes가 message를 decrypt하고 agent queue에 넣습니다.
4. 즉시 acknowledge합니다. 이 응답은 silent이며 사용자에게 표시되지 않습니다.
5. agent가 request를 처리합니다. 보통 3-30분이 걸립니다.
6. reply는 WeCom message/send API를 통해 proactive하게 전달됩니다.

prerequisites

• admin access가 있는 WeCom enterprise account
• aiohttp, httpx Python package(default install에 포함)
• callback URL로 접근 가능한 public server 또는 ngrok 같은 tunnel

setup

1. WeCom에서 self-built app 만들기

1. WeCom Admin Console → Applications → Create App으로 이동합니다.
2. admin console 상단에 표시되는 Corp ID를 기록합니다.
3. app setting에서 Corp Secret을 생성합니다.
4. app overview page의 Agent ID를 기록합니다.
5. Receive Messages 아래에서 callback URL을 설정합니다.
   • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
   • Token: random token 생성(WeCom이 제공)
   • EncodingAESKey: key 생성(WeCom이 제공)

2. environment variable 설정

.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=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. gateway 시작

hermes gateway

hermes gateway start는 hermes gateway install로 systemd/launchd service를 등록한 뒤에만 사용하세요.

callback adapter는 설정된 port에서 HTTP server를 시작합니다. WeCom은 GET request로 callback URL을 verify한 뒤, POST로 message를 보내기 시작합니다.

configuration reference

config.yaml의 platforms.wecom_callback.extra 아래에 설정하거나 environment variable을 사용합니다.

Setting	Default	Description
corp_id	—	WeCom enterprise Corp ID(required)
corp_secret	—	self-built app의 Corp secret(required)
agent_id	—	self-built app의 Agent ID(required)
token	—	callback verification token(required)
encoding_aes_key	—	callback encryption용 43-character AES key(required)
host	0.0.0.0	HTTP callback server bind address
port	8645	HTTP callback server port
path	/wecom/callback	callback endpoint URL path

multi-app routing

여러 self-built app을 운영하는 enterprise라면(예: department나 subsidiary별 app), config.yaml에 apps list를 설정합니다.

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..."

cross-corp collision을 막기 위해 user는 corp_id:user_id로 scope됩니다. 사용자가 message를 보내면 adapter는 사용자가 어느 app(corp)에 속하는지 기록하고, 올바른 app의 access token으로 reply를 route합니다.

access control

app과 상호작용할 수 있는 user를 제한합니다.

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

endpoints

adapter가 노출하는 endpoint:

Method	Path	Purpose
GET	/wecom/callback	URL verification handshake(setup 중 WeCom이 보냄)
POST	/wecom/callback	encrypted message callback(WeCom이 user message를 보냄)
GET	/health	health check - {"status": "ok"} 반환

encryption

모든 callback payload는 EncodingAESKey를 사용한 AES-CBC로 암호화됩니다. adapter는 다음을 처리합니다.

• Inbound: XML payload decrypt, SHA1 signature verify
• Outbound: proactive API로 전송되는 reply(callback response로 encrypt하지 않음)

crypto implementation은 Tencent의 공식 WXBizMsgCrypt SDK와 호환됩니다.

limitations

• No streaming - agent가 끝난 뒤 complete message로 reply가 도착합니다.
• No typing indicators - callback model은 typing status를 지원하지 않습니다.
• Text only - 현재 input은 text message를 지원합니다. image/file/voice input은 아직 구현되지 않았습니다. 다만 agent는 WeCom platform hint를 통해 outbound media capability(image, document, video, voice)를 알고 있습니다.
• Response latency - agent session은 3-30분이 걸릴 수 있습니다. 사용자는 처리가 완료된 뒤 reply를 봅니다.