Lors de la mise en place d'une application WeCom (WeChat Work), il est essentiel de configurer un serveur de réception des messages via une URL de callback. Pour cela, vous devez disposer d’un domaine public accessible depuis Internet qui pointe vers votre environnement local.

Parmi les outils testés pour cette tâche, cloudflared, fourni par Cloudflare, s’est avéré être une solution gratuite et efficace.

Installation de cloudflared

• Sous Windows :

https://github.com/cloudflare/cloudflared/releases

• Sous macOS :

brew install cloudflare/cloudflare/cloudflared

Sur Mac, assurez-vous que votre connexion dispose d’un proxy si nécessaire, afin d’éviter tout échec lors du téléchargement.

• Sous Linux :

wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O cloudflared
chmod +x cloudflared

Démarrage du tunnel

Pour exposer le port local 9090 (ou autre selon votre configuration backend) :

cloudflared tunnel --url http://localhost:9090

Une fois lancé, l’outil affichera dans les logs un domaine public généré automatiquement. Si vous ne trouvez pas immédiatement ce domaine, copiez-collez les logs dans un assistant IA pour extraction.

Mise en place du contrôleur Java

Voici un exemple d’implémentation Spring Boot permettant de gérer la vérification initiale du webhook :

@RestController
@RequestMapping("/callback/wecom")
public class WeComMessageReceiver {

    @Value("${app.wecom.token}")
    private String wecomToken;

    @Value("${app.wecom.aesKey}")
    private String aesKey;

    @Value("${app.wecom.corpId}")
    private String corpIdentifier;

    @GetMapping(value = "/verify", produces = MediaType.TEXT_PLAIN_VALUE)
    public ResponseEntity<String> handleVerification(
            @RequestParam("msg_signature") String signature,
            @RequestParam String timestamp,
            @RequestParam String nonce,
            @RequestParam String encryptedEchoStr) {

        System.out.println("Requête de validation reçue.");
        System.out.println("Signature : " + signature);
        System.out.println("Timestamp : " + timestamp);
        System.out.println("Nonce : " + nonce);
        System.out.println("Encrypted EchoStr : " + encryptedEchoStr);

        try {
            WXBizMsgCrypt decryptor = new WXBizMsgCrypt(wecomToken, aesKey, corpIdentifier);
            String decryptedEcho = decryptor.VerifyURL(signature, timestamp, nonce, encryptedEchoStr);
            System.out.println("✅ Validation réussie : " + decryptedEcho);
            return ResponseEntity.ok(decryptedEcho);
        } catch (Exception e) {
            System.err.println("❌ Échec de déchiffrement : ");
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Validation failed");
        }
    }
}

Cette implémentation utilise la classe utilitaire WXBizMsgCrypt fournie par Tencent. Vous pouvez la télécharger ici :

https://developer.work.weixin.qq.com/devtool/introduce?id=10128

Assurez-vous d’utiliser la version Java adaptée à votre projet. Si vous travailez avec JDK supérieur à 1.6, ajoutez également la dépendance suivante dans votre fichier pom.xml :

<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.19.0</version>
</dependency>

En cas de gestion manuelle des dépendances, téléchargez directement depuis :

https://commons.apache.org/proper/commons-codec/download_codec.cgi

Fichier de configuration YAML

Exemple de configuration dans application.yml :

app:
  wecom:
    token: mySecureRandomToken
    aesKey: abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGH
    corpId: your_corporate_id_from_wecom_admin_panel

Les valeurs doivent correspondre strictement à celles renseignées dans l'interface administrateur de WeCom.

Configuration finale dans l’administration WeCom

Renseignez l’URL de callback comme suit :

https://[domaine-public]/callback/wecom/verify

Où [domaine-public] est celui généré précédemment via cloudflared.

Après avoir sauvegardé, si tout est correctement configuré, vous verrez apparaître dans vos logs Java une réponse similaire à :

✅ Validation réussie : randomEchoStringFromWeCom

Cela signifie que votre serveur est prêt à recevoir les notifications envoyées par WeCom.