Webhooks概述

webhook在BigCommerce商店发生特定事件时通知应用程序。例如当:

• 创建订单，
• 产品的库存会发生变化
• 一个项目被添加到购物者的购物车

本文概述了BigCommerce上的webhook行为。有关完整的webhook API参考，请参阅API参考> Webhooks。关于为特定商店事件创建webhook的循序渐进的webhook教程，请参阅Webhooks教程。

创建一个webhook

创建一个webhook，发送一个帖子请求/ stores / {{store_hash}} / v2 /钩子。

Webhooks POST请求头和正文

文章https://api.bigcommerce.com/stores/ {{STORE_HASH}} / v2 /钩子X-Auth-Token:{{access_token}}内容类型:application / json接受:application / json{“范围”:“商店/订购/更新”,“目的地”:“https://665b65a6.ngrok.io/webhooks”,“活跃”:真的}

回复

{“created_at”:1580329317,“目的地”:“https://665b65a6.ngrok.io/webhooks”,“标题”:空值,“id”:20172984.,“活跃”:真的,“范围”:“商店/订购/ *”,“store_hash”:“{{STORE_HASH}}”,“updated_at”:1580329317}

回调有效载荷

当触发Webhook时，BigCommerce会帖子一个光有效载荷包含到目标服务器的事件详细信息。例如，数据对象商店/订购/ stateUpdated仅包含订单id:

Statusupdated Post Request Body

{“可以”:11111,“制片人”:“商店/中的”,“范围”:“存储/订单/ statusUpdated”,“数据”:{“类型”:“命令”,“id”:173331.},“希”:“3 f9ea420af83450d7ef9f78b08c8af25b2213637”}

然后可以向/订单/ {id}获取完整订单详细信息。

有关特定的Webhook事件及其有效载荷的更多信息，请参阅Webhook活动。

处理回调

若要确认已接收回调而没有发出问题，目标服务器必须返回HTTP 200响应-没有响应，或任何外部响应200.范围表示没有收到回呼。如果发生这种情况，webhook服务将使用重试机制下面描述。

需要设置一个快速的Webhook目的地URL进行测试？看用于调试和测试Webhooks的工具。

回调重试机制

webhooks服务将尽其所能将事件传递给目标回调URI。对于应用程序来说，最佳实践是在采取任何其他会减慢其响应的操作之前响应回调。否则会触发BigCommerce的回调重试机制。

webhook服务可以快速连续地向单个URI发送许多有效负载。因此，我们使用一个横跨**两分钟窗口**的滑动比例来计算每个远程目的地的回调响应成功率。当webhook服务接收到一个2 xx响应，目的地的成功计数增加。如果没有响应或远程服务器超时，则会增加目标的失败计数。基于这两个数字，计算成功比率。

以下过程将确定目的地URI是否被列入黑名单：

1. 一旦触发了Webhook，服务会检查您的回调URI是否在黑名单上
2. 如果不是，我们将根据远程服务器的成功/失败计数计算远程服务器的成功率两分钟窗口
3. 如果在两分钟窗口中的任何一点，成功/失败比率下降到以下90％，目标URI的域将被列入黑名单三分钟
4. 在这段时间内触发的Webhook事件将被发送到我们的重试队列中，稍后当该域不再被列入黑名单或重试队列时间已经过时再执行

一旦域名不再被列入黑名单，所有新的webhook请求将被发送。黑名单期间发送到重试队列的事件请求将根据重试队列调度调度下发。

然后，webhook调度程序将尝试多次重试(以递增的间隔)，直到达到最大重试限制。

队列	时间间隔
dispatches.retries.60	60秒后重试
派遣.180	180秒后重试
dispatches.retries.300	300秒后重试
派遣.Retries.600	600秒后重试
派遣.Retries.900.	900秒后重试
调度.1800	1800秒后重试
dispatches.retries.3600	3600秒后重试
派遣.Retries.7200.	7200秒后重试
派遣.1600	21600秒后重试
dispatches.retries.50400	50400秒后重试
派遣.Retries.86400.	86400秒后重试

最终重试尝试后（累积48小时在第一次传递尝试之后，将停用Webhook，并将发送电子邮件，将发送到为订阅应用程序注册的电子邮件地址。重新激活webhook，设置活跃回真的通过一个把请求/钩子/ {id}。

POST APP卸载操作

为了避免累积未使用的webhook, BigCommerce会在app卸载时自动删除注册的webhook。

安全

为确保Webhook回调请求是安全的，BigCommerce采用以下预防措施：

• Webhook有效载荷包含关于存储和事件的最小信息
• Webhook有效载荷已发送TLS加密连接
• 创建Webhook请求接受一个可选的头对象，可以用来验证回调请求

包含标题对象的发布请求

{“范围”:“存储/车/ lineItem / *”,“目的地”:“{{DESTINATION_URL}}”,“活跃”:真的,“标题”:{“用户名”:“你好”,“密码”:“再见”}}

当向目标服务器发出回调请求时，BigCommerce将发送指定的头信息-这允许通过基本身份验证来保护webhook目标uri。

故障排除

没有收到webhook事件回调

如果您的应用程序没有返回HTTP 200在收到WebHook事件有效载荷后，BigCommerce将其视为失败。BigCommerce将继续尝试一点48小时。在该时间结束时，BigCommerce在应用程序注册期间向电子邮件地址发送电子邮件并通过设置禁用WebHook活跃标志为假。

看看webhook仍然是活动的，制作一个得到请求/钩子/ {id}并检查的价值活跃属性。

如果您收到电子邮件或发现活跃是假，试试以下方法:

• 验证应用程序是否响应回调200.响应。
• 通过访问https://globalsign.sllabs.com/，验证目标服务器是否具有有效的TLS / SSL安装程序。以下任何一个都将导致TLS / SSL握手失败：
  • 自签名证书
  • 证书上的主机名与DNS设置中的主机名不匹配
  • 密钥和信任存储区没有配置所需的中间证书

一旦问题得到解决，设置活跃来真的通过一个把请求/钩子/ {id}- BigCommerce再次开始发送活动回调请求。

制作时没有200次回复帖子来/钩子

• 检查机器制造上的TLS/SSL配置帖子要求。
• 验证帖子请求包含所需的HTTP标题:

创建钩子POST请求

文章https://api.bigcommerce.com/stores/ {{STORE_HASH}} / v2 /钩子接受:application / json内容类型:application / jsonX-Auth-Token:{{access_token}}

工具

下面是一些第三方工具的集合，可以用来帮助webhook的开发、测试和调试:

工具	描述
诺克	容易设置隧道localhost.和一个诺克公共URL测试计算机上的回调请求
Webhook Tester.	测试Webhooks和其他类型HTTP浏览器中的请求

相关资源

文章

• Webhook教程
• Webhook活动

终点

• 人参考