# 接入指南

更新时间：2024-09-06 11:22:06

# WebHook是什么？

Webhook 是一个 API 概念，是微服务 API 的使用范式之一，也被称为反向 API。

即前端不主动发送请求，完全由服务端推送。举个例子，你的好友发了一条朋友圈，这个事件发生后，服务端将这条朋友圈推送给所有其他好友的客户端，这就是 Webhook 的典型场景。简单来说，Webhook 就是一个接收 HTTP POST（或GET，PUT，DELETE）的URL。如果你实现了一个Webhook 的 API ，当一个事件发生的时候，系统会向这个配置好的 URL 发送一条信息，与请求-响应式不同，使用 Webhook 你可以实时接受到变化。

# WebHook使用场景

使用场景	场景举例
事件订阅	某些快手内部发生的事件行为，例如弹幕小玩法，开发者需要实时感知直播间内的点赞、评论、送礼行为
消息通知	向开发者推送相关数据,例如通知开发者用户授权结果等
异步化/同步转异步	在某些异步API的场景，比如小程序支付，开发者调用小程序支付API后，小程序内部需要走很长的流程才能完成支付，开发者无法在支付接口实时获取到直接结果，可以通过Webhook的方式在异步执行完成支付流程后通知到开发者，防止开发者一直轮询接口

# webhook调用流程

当事件(Event)发生时，开放平台会通过https post的方式将事件推送到开发者配置好的回调地址。通过Webhooks机制可以方便开发者第一时间获取到关注的事件变化。

整体调用如图示：

# 回调地址配置和校验

在管理中心 Webhooks页填写你要配置的回调地址。完成请求网址编辑后，点击保存按钮时，开放平台会向你配置的网址推送一个 POST 请求, 该请求用于验证你配置的网址的合法性。需要用户按照协议返回对应的信息,来通过验证,协议见测试事件
具体配置见：
1、在管理中心，打开你的应用：

2、应用配置里，在用户时间推送里配置消息回调地址：

# 回调地址要求和说明

1、webhook发送的数据结构
Webhooks会给第三方发送四个固定字段：data（业务数据，对应eventData）、message_id（消息ID）、event（事件名称，对应eventName）、app_id（appId，对应appId）、timestamp（发送时间）；
以下是个简单demo：

{  
    "data":{   // data 中的数据结构取决于 webHookEntity 具体由业务方自定义  
        "photo_id":"3xwv74u6uimf8kwa",  
        "author_open_id":"5b748d86d614d5c4c0656638e8f73fe6a",  
          "reason":"视频解绑原因",  
    },  
    "message_id":"fcc935c7-e144-4ebd-903e-457c3f50816ba", // 每次随机生成的ID  
    "event":"UNBIND_PLC",  
    "app_id":"ks7005912187730767111",  
    "timestamp":1672890955411  
}

2、对回调服务响应参数的要求
必须满足规则：返回http状态码是200，并且返回字段result=1代表成功，其他都是代表失败，失败平台会重试调用，调用次数根据事件名称配置化

{  
以下是第三方处理成功的返回参数demo：  
response:[HttpResponseContent{code=200} ResponseContent{success=true, responseStr='{"result":1,"message_id":"99443c09-ddf6-4d30-a84d-f92c52e25339"}', errorMag='null'}]  
}

# 消息发送说明

1、webhook本身不支持幂等，需要业务方自己做幂等控制：
（1）webhook只是一个通道，webhook本身不支持幂等，调用几次sdk就会调用几次callback接口，需要接入方做好幂等控制；
（2）message_id由快手内部业务方调用webhook，每调用一次都会随机生成的ID，不可用于业务幂等控制，如果需要做业务幂等，接入方需要自己生产幂等参数放到eventData，让第三方开发者根据eventData里的幂等参数做幂等控制。

2、webhook本身会重试，需要第三方做好幂等控制：
（1） webhook调用第三方支持重试，重试次数可配置，webhook保证业务方如果调用webhook成功，最终一定能通知到第三方；
（2）第三方开发者需要根据message_id做好幂等控制。

即：第三方需要根据eventData里的业务方幂等参数（如果有的话）或messageId两个参数分别去重做幂等控制。
如果eventData里有业务方幂等参数则只是用eventData里有业务方幂等参数做幂等控制就行，不需要再用message_id；

3、webhook是异步调用第三方的，如果业务方想拿到第三方响应结果，需要接webhook的消息日志MQ（包括调用第三方成功事件），但是调用第三方和记录日志MQ不是原子的，webhook不保证调用第三方成功后一定有日志MQ，解决办法：如果业务方没有收到日志MQ则重试调用webhook；

4、webhook不保证消息发到开发者的顺序和业务方调用webhook的顺序一致，如果需要保证消息的顺序，需要业务方自己设计处理。

5、如果开发者没有返回或者返回的result不等于1，则平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！

# 消息来源验证

用户可通过请求header中的 kwaisign 字段来判断消息的可靠性。
webhook内部会对数据进行签名,开发者需要对签名的合法性进行验证，签名字段会放到http header里，字段名称：kwaisign，具体签名方式和签名参数见：https://open.kuaishou.com/docs/develop/server/epay/appendix.html （附录1、请求签名算法）