Eyun 开发者文档

Appearance

POST{BASE_URL}/wx-api/webhook/set
写操作回调配置JSON · Bearer App Token

设置或更新回调地址 ​

用 App Token 设置你的回调地址；系统收到企微事件后按此地址推送给你。每个应用一个回调，重复调用为更新。

说明与注意 ​

  • url 必填（http/https）；events 不填=订阅全部事件；secret 不填自动生成。
  • secret 明文仅首次创建时返回一次，用于校验签名：X-Eyun-Signature: sha256=<hmac(secret, body)>。更新已有配置不返回也不改 secret。
  • 密钥丢失时，先删除回调配置，再重新设置获取新 secret，并同步更新验签密钥；也可联系对接人。

请求参数 ​

参数必填类型说明
url是string你的回调接收地址（http/https）。示例：https://your.domain/hook
events否array<string>订阅事件名；不填=全部（见可订阅事件列表）。示例：["message.received","friend.added"]
secret否string首次创建时使用的签名密钥；不填自动生成。更新已有配置不更改密钥
status否stringactive 推送中、paused 暂停推送

请求示例 ​

http
POST {BASE_URL}/wx-api/webhook/set
Authorization: Bearer <你的 App Token>
Content-Type: application/json

{
  "url": "https://your.domain/hook",
  "events": [
    "message.received",
    "friend.added"
  ]
}
bash
curl -X POST '{BASE_URL}/wx-api/webhook/set' \
  -H 'Authorization: Bearer <你的 App Token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://your.domain/hook",
  "events": [
    "message.received",
    "friend.added"
  ]
}'
python
import requests

url = "{BASE_URL}/wx-api/webhook/set"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
  "url": "https://your.domain/hook",
  "events": [
    "message.received",
    "friend.added"
  ]
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/wx-api/webhook/set";
String body = "{\n" +
    "  \"url\": \"https://your.domain/hook\",\n" +
    "  \"events\": [\n" +
    "    \"message.received\",\n" +
    "    \"friend.added\"\n" +
    "  ]\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的 App Token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
php
<?php

$url = '{BASE_URL}/wx-api/webhook/set';
$body = <<<'JSON'
{
  "url": "https://your.domain/hook",
  "events": [
    "message.received",
    "friend.added"
  ]
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的 App Token>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

响应示例 ​

json
{
  "code": 0,
  "data": {
    "webhook": {
      "id": "whk_…",
      "name": "OpenAPI 回调",
      "url": "https://your.domain/hook",
      "events": [
        "message.received",
        "friend.added",
        "friend.deleted",
        "contact.modified",
        "instance.online",
        "instance.offline"
      ],
      "status": "active",
      "signingEnabled": true
    },
    "secret": "whs_首次返回一次"
  },
  "message": "ok"
}

下一步 ​