事件回调

概要

事件回调,又称 Webhook,是指当特定事件发生时,Udesk 将特定的数据以固定的格式发送给您指定的回调地址。

Udesk 的事件回调支持以下事件:

事件名 说明
Customer_create 新建客户时
Customer_update 修改客户时
Customer_destroy 删除客户时
Organization_create 新建客户公司时
Organization_update 修改客户公司时
Organization_destroy 删除客户公司时

如果需要使用 Udesk 事件回调功能,您要执行以下步骤:

  1. 编写代码,实现事件回调处理接口,并提供事件回调地址;
  2. 调用设置事件回调地址接口,将您实现的事件回调处理接口地址设置事件回调地址;
  3. 调用设置事件回调类型接口,根据您的需要设置需要接收哪些事件回调;
  4. 调用设置事件回调的content_type接口,根据您的需要设置content_type的值;

编写事件回调处理接口

该接口需要由您实现,并且满足特定的要求。

Udesk 会使用 POST 方法请求您提供的回调地址,并将数据作为请求体(Request Body)传送。

请求体的数据结构如下:

属性 类型 说明
action 字符串 事件类型
message 对象 事件数据

不同事件 message 所有不同。

Customer_create 事件

“message”的数据结构参考客户数据

示例:

{
    "action": "Customer_create",
    "message": {
        "id": 1,
        "nick_name": "测试用户",
        "level": "normal",
        "description": null,
        "owner_id": 1,
        "owner_group_id": 1,
        "custom_fields": {
            "SelectField_1": ["0"],
            "SelectField_2": ["0"]
        },
        "open_api_token": null,
        "organization_id": null,
        "is_blocked": false,
        "tags": [],
        "email": "customer@sample.com",
        "other_emails": [],
        "cellphones": [
            {
              "id": 1,
              "content": "13000000001"
            }
        ],
        "platform": "手工录入"
    }
}

Customer_update 事件

“message”的数据结构如下:

{
    "id": 客户id,
    "changes": {
        "属性名": [原值, 变更后的值]
    }
}

其中“属性名”参看客户数据

示例:

{
    "action": "Customer_update",
    "message": {
        "id": 1,
        "changes": {
            "nick_name": ["测试客户1", "测试客户2"],
            "owner_id": [1, 2]
        }
    }
}

Customer_destroy 事件

“message”的数据结构如下:

{
    "id": 被删除的客户id
}

示例

{
    "action": "Customer_destroy",
    "message": {
        "id": 1
    }
}

Organization_create 事件

“message”的数据结构参考客户公司数据

示例:

{
    "action": "Organization_create",
    "message": {
        "id": 1,
        "name": "测试公司1",
        "domains": "http://www.test1.com",
        "custom_fields": {
            "TextField_1": "测试文本",
            "SelectField_1": ["0"]
        },
        "description": "该公司仅用来举例"
    }
}

Organization_update 事件

“message”的数据结构如下:

{
    "id": 客户公司id,
    "changes": {
        "属性名": [原值, 变更后的值]
    }
}

其中“属性名”参看客户公司数据

示例:

{
    "action": "Organization_update",
    "message": {
        "id": 1,
        "changes": {
            "name": ["测试公司1", "测试公司2"]
        }
    }
}

Organization_destroy 事件

“message”的数据结构如下:

{
    "id": 被删除的客户公司id
}

示例

{
    "action": "Organization_destroy",
    "message": {
        "id": 1
    }
}

设置事件回调地址接口

该接口用于设置事件回调地址 鉴权:参看鉴权方法

请求方法

POST /set_url

请求参数(Request Body)

参数名 必填 类型 说明
push_url 字符串 事件回调地址

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 返回结果说明
push_url 字符串 修改后的事件回调地址

示例

curl http://demo.udesk.cn/open_api_v1/set_url?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8
-X POST \
-H 'content-type: application/json' \
-d '
{
    "push_url": "http://www.demo.com/push_url"
}'

返回

{
    "code": 1000,
    "message": "OK",
    "push_url": "http://www.demo.com/push_url"
}

设置事件回调的content_type接口

该接口用于设置事件回调地址
鉴权:参看鉴权方法

请求方法

POST /set_push_content_type

请求参数(Request Body)

参数名 必填 类型 说明
push_content_type 字符串 事件回调请求的content_type

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
push_url 字符串 修改后的事件回调地址

示例

curl http://demo.udesk.cn/open_api_v1/set_push_content_type?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8
-X POST \
-H 'content-type: application/json' \
-d '
{
    "push_content_type": "JSON"
}'

返回

{
    "code": 1000,
    "push_content_type": "JSON"
}

设置事件回调类型接口

该接口用于设置需要接收哪些事件回调 鉴权:参看鉴权方法

请求方法

POST /set_url/set_permissions

请求参数(Request Body)

参数名 必填 类型 说明
permissions 对象 设置集合

permissions 的数据结构

参数名 必填 类型 说明
customer_create 布尔 是否接收客户创建事件
customer_update 布尔 是否接收客户修改事件
customer_destroy 布尔 是否接收客户删除事件
organization_create 布尔 是否接收公司创建事件
organization_update 布尔 是否接收公司修改事件
organization_destroy 布尔 是否接收公司删除事件

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 返回结果说明
permissions 对象 修改后的设置集合,结构与参数相同

示例

curl http://demo.udesk.cn/open_api_v1/set_permissions?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "permissions": {
        "organization_create":true,
        "organization_update": true,
        "organization_destroy": true,
        "customer_create": true,
        "customer_update": true,
        "customer_destroy": true
    }
}'

返回

{
    "code": 1000,
    "message": "OK",
    "permissions": {
        "organization_create":true,
        "organization_update": true,
        "organization_destroy": true,
        "customer_create": true,
        "customer_update": true,
        "customer_destroy": true
    }
}