广告实时数据Webhook
收藏我的收藏
收藏功能描述
在开发者平台控制台上配置好小程序的 webhook 功能，并开启订阅实时广告数据事件，系统会将实时广告数据推送至平台上配置的 URL 地址上，实现这个 URL 的开发者服务端即可接收到实时广告数据，消除轮询查询接口所带来的固定延迟和无效性能消耗。
查询接口相关文档：广告数据实时下发接口
接入流程
实现challenge和消息校验
参考：小程序webhook
广告实时数据事件的重试机制说明以本文 档为准。
实现接收事件逻辑
一条或多条广告数据会被打包进请求体中，作为一次事件推送。
- 1.消息内容
名称 | 类型 | 是否必填 | 描述 | 示例值 |
event | string | 是 | 对应于平台上订阅的某个事件英文名称，实时广告数据对应的事件名称为 "ma_ecpm" | ma_ecpm |
client_key | string | 是 | 小程序ID | tt5daf2b12c285xxxx |
from_user_id | string | 否 | ma_ecpm事件下固定为空 | '' |
content | string | 否 | 一条或多条广告数据记录的JSON字符串，最外层是个列表 | [{\"id\":\"1054\",\"mp_id\":\"tt5daf2b12c2857910\",\"cost\":\"10000\",\"open_id\":\"S2ecRNRDjx1lD1Fr\",\"event_time\":\"1715174172\",\"req_id\":\"123123\",\"ad_type\":\"激励视频广告\"}] |
log_id | string | 是 | 内部链路事件推送的日志ID，用于提供给平台 debug | 021715174212333fdbddc0300ff0501923618698dde1fe7bd105a |
一条或多条广告数据以 JSON 字符串的形式填充至 content 字段中，JSON 最外层是个列表。
名称 | 类型 | 是否必填 | 描述 |
id | string | 是 | 记录唯一标识，随 event_time 趋势递增 |
mp_id | stirng | 是 | 小程序ID |
cost | string | 是 | 广告消耗，单位为：十万分之一元 |
open_id | string | 是 | 用户OpenID（由于 OpenID 实现为弱依赖且存在下游稳定性问题，如果 OpenID 返回为空且需要重试，可以将 http 响应码返回为400） |
event_time | string | 是 | 广告计费发生时间戳，单位秒 |
ad_type | string | 是 | 小程序广告类型 |
req_id | string | 是 | 无需关注 |
body示例
{ "log_id": "021715689753164fdbddc0300150239894918b04000001244bba2", "event": "ma_ecpm", "client_key": "tt5daf2b12c2857910", "from_user_id": "", "content": "[{\"id\":\"10000000509\",\"mp_id\":\"tt5daf2b12c2857910\",\"cost\":\"3412\",\"open_id\":\"9eMmlmrIzcr-i96V\",\"event_time\":\"1715689728\",\"req_id\":\"202404301410333BA589251C766C16FED4\",\"ad_type\":\"激励视频广告\"}， {\"id\":\"10000000505\",\"mp_id\":\"tt5daf2b12c2857910\",\"cost\":\"1501\",\"open_id\":\"9eMmlmrIzcr-i96V\",\"event_time\":\"1715689706\",\"req_id\":\"202404301410333BA589251C766C16FED4\",\"ad_type\":\"激励视频广告\"}]" }
Content 字段示例：
[{ "id": "10000000509", "mp_id": "tt5daf2b12c2857910", "cost": "3412", "open_id": "9eMmlmrIzcr-i96V", "event_time": "1715689728", "req_id": "202404301410333BA589251C766C16FED4", "ad_type": "激励视频广告" }, { "id": "10000000505", "mp_id": "tt5daf2b12c2857910", "cost": "1501", "open_id": "9eMmlmrIzcr-i96V", "event_time": "1715689706", "req_id": "202404301410333BA589251C766C16FED4", "ad_type": "激励视频广告" }]
- 2.HTTP响应码约定
如果开发者服务端确定接收到某次事件的广告数据，返回 [200,300) 范围内的响应码。
如果返回其他响应码，系统认为开发者服务端异常及事件推送失败。
由于 OpenID 字段实现为弱依赖且存在下游稳定性问题，如果 OpenID 返回为空且需要重新推送获取非空 OpenID 时，可以将响应码返回为 400。如果超出 10 次重试推送仍为空（几乎不可能出现），可以延迟一段时间通过查询接口查询相应记录。
- 3.HTTP响应体
系统不处理响应体。
- 4.超时控制
对于某次事件推送如果开发者服务端超过 2.5 秒未响应，系统认为事件推送失败。
- 5.事件推送失败重试策略
当某次推送被认为是失败时（超时或非 [200,300) 响应码），系统会累积这些推送失败的广告数据记录，并每隔 1 分钟定期重新打包和推送（可能与新到来的记录打包到一个请求体中投递）。如果被重新打包推送超过 10 次，那么这条广告记录会被系统丢弃。
开启订阅事件
以下两种方式二选一：
按钮订阅
openapi 开启事件订阅
curl --location 'https://open.douyin.com/api/platform/v1/webhook/update_event_status/' \ --header 'Content-Type: application/json' \ --header 'access-token: clt.11ba16cf7c099bc1b564955ff517840f6vkpxeHAYpy7QVyGq0rkwCs4UR9U' \ --data '{ "event_list":[ { "event":"ma_ecpm", "status":1 } ] }'
语义说明
实时性
绝大部分情况是从广告服务端发送广告开始 1 分钟内能将数据推送至开发者服务端，最大延迟不会超过 10 分钟。若大量数据超过 10 分钟为系统异常，会有监控报警并被及时处理。
幂等性
由开发者服务端依据 (event_time, open_id, cost) 三元组保证
另外值得提醒的是，原查询接口数据库里的记录也是没有去重的，也就是说存在这样的情况：查询出来的两条数据记录本质上是一次用户看广告事件所产生的，即除了 ID 不一样，其他字段完全一样（这一点前 owner 没有了解到并在文档里注明）。这意味着开发者如果需要准确计算总收益，务必自主去重。去重所依赖的字段：ecpm 接口为 (event_time, open_id, cost)。
重试策略
- •当某次推送被认为是失败时（超时或非 [200,300) 响应码），系统会累积这些推送失败的广告数据记录，并每隔1分钟定期重新打包和推送（可能与新到来的记录打包到一个请求体中投递）。如果被重新打包推送超过 10 次，那么这条广告记录会被系统丢弃。
- •为了避免资源浪费，系统会统计 5 分钟内的开发者服务端超时或非正常响应码次数，若次数超出阈值，则在这 5 分钟内不再发起请求，等到下一个 5 分钟窗口重置次数并继续请求。
超时控制
对于某次事件推送如果开发者服务端超过 2.5 秒未响应，系统认为事件推送失败并触发重试策略。
顺序性
系统无法保证先被发送广告的数据记录被先推送。
完整性
系统会将产生的每一条广告数据记录都至少一次推送至开发者服务端中，但开发者服务端存在失败的可能，记录可能会因为重试次数超限而被丢弃，因此开发者需要做好监控来识别丢失的情况，并通过调用查询接口来补偿丢失数据。
衡量 webhook 推送的数据是否丢失是以数据库为准的，目的是为了保证跟查询接口相比不丢失记录。如果认为 webhook 推送少了数据，但通过查询接口也查询不到想要的数据，说明存在其他数据缺失或无数据的原因，这些可能的情况列举在查询接口文档中，如果无法解决请 oncall 进来。
