[[273544]]

 Webhook 可用于外部系統(tǒng)通知你的系統(tǒng)發(fā)生了某個(gè)事件或更新。可能最知名的 Webhook 類(lèi)型是支付服務(wù)提供商（PSP）通知你的系統(tǒng)支付狀態(tài)有了更新。

它們通常以監(jiān)聽(tīng)的預(yù)定義 URL 的形式出現(xiàn)，例如 http://example.com/webhooks/payment-update。同時(shí)，另一個(gè)系統(tǒng)向該 URL 發(fā)送具有特定有效載荷的 POST 請(qǐng)求（例如支付 ID）。一旦請(qǐng)求進(jìn)入，你就會(huì)獲得支付 ID，可以通過(guò) PSP 的 API 用這個(gè)支付 ID 向它們?cè)儐?wèn)最新?tīng)顟B(tài)，然后更新你的數(shù)據(jù)庫(kù)。

其他例子可以在這個(gè)對(duì) Webhook 的出色的解釋中找到：https://sendgrid.com/blog/whats-webhook/。

只要系統(tǒng)可通過(guò)互聯(lián)網(wǎng)公開(kāi)訪(fǎng)問(wèn)（這可能是你的生產(chǎn)環(huán)境或可公開(kāi)訪(fǎng)問(wèn)的臨時(shí)環(huán)境），測(cè)試這些 webhook 就相當(dāng)順利。而當(dāng)你在筆記本電腦上或虛擬機(jī)內(nèi)部（例如，Vagrant 虛擬機(jī)）進(jìn)行本地開(kāi)發(fā)時(shí)，它就變得困難了。在這些情況下，發(fā)送 webhook 的一方無(wú)法公開(kāi)訪(fǎng)問(wèn)你的本地 URL。此外，監(jiān)視發(fā)送的請(qǐng)求也很困難，這可能使開(kāi)發(fā)和調(diào)試變得困難。

因此，這個(gè)例子將解決：

• 測(cè)試來(lái)自本地開(kāi)發(fā)環(huán)境的 webhook，該環(huán)境無(wú)法通過(guò)互聯(lián)網(wǎng)訪(fǎng)問(wèn)。從服務(wù)器向 webhook 發(fā)送數(shù)據(jù)的服務(wù)無(wú)法訪(fǎng)問(wèn)它。
• 監(jiān)控發(fā)送的請(qǐng)求和數(shù)據(jù)，以及應(yīng)用程序生成的響應(yīng)。這樣可以更輕松地進(jìn)行調(diào)試，從而縮短開(kāi)發(fā)周期。

前置需求：

• 可選：如果你使用虛擬機(jī)（VM）進(jìn)行開(kāi)發(fā)，請(qǐng)確保它正在運(yùn)行，并確保在 VM 中完成后續(xù)步驟。
• 對(duì)于本教程，我們假設(shè)你定義了一個(gè) vhost：webhook.example.vagrant。我在本教程中使用了 Vagrant VM，但你可以自由選擇 vhost。
• 按照這個(gè)安裝說(shuō)明安裝 ngrok。在 VM 中，我發(fā)現(xiàn)它的 Node 版本也很有用：https://www.npmjs.com/package/ngrok，但你可以隨意使用其他方法。

我假設(shè)你沒(méi)有在你的環(huán)境中運(yùn)行 SSL，但如果你使用了，請(qǐng)將在下面的示例中的端口 80 替換為端口 433，http:// 替換為 https://。

使 webhook 可測(cè)試

我們假設(shè)以下示例代碼。我將使用 PHP，但請(qǐng)將其視作偽代碼，因?yàn)槲伊粝铝艘恍╆P(guān)鍵部分（例如 API 密鑰、輸入驗(yàn)證等）沒(méi)有編寫(xiě)。

第一個(gè)文件：payment.php。此文件創(chuàng)建一個(gè) $payment 對(duì)象，將其注冊(cè)到 PSP。然后它獲取客戶(hù)需要訪(fǎng)問(wèn)的 URL，以便支付并將用戶(hù)重定向到客戶(hù)那里。

請(qǐng)注意，此示例中的 webhook.example.vagrant 是我們?yōu)殚_(kāi)發(fā)設(shè)置定義的本地虛擬主機(jī)。它無(wú)法從外部世界進(jìn)入。

<?php
/*
 * This file creates a payment and tells the PSP what webhook URL to use for updates
 * After creating the payment, we get a URL to send the customer to in order to pay at the PSP
 */
$payment = [
    'order_id' => 123,
    'amount' => 25.00,
    'description' => 'Test payment',
    'redirect_url' => 'http://webhook.example.vagrant/redirect.php',
    'webhook_url' => 'http://webhook.example.vagrant/webhook.php',
];
 
$payment = $paymentProvider->createPayment($payment);
header("Location: " . $payment->getPaymentUrl());

第二個(gè)文件：webhook.php。此文件等待 PSP 調(diào)用以獲得有關(guān)更新的通知。

<?php
/*
 * This file gets called by the PSP and in the $_POST they submit an 'id'
 * We can use this ID to get the latest status from the PSP and update our internal systems afterward
 */
 
$paymentId = $_POST['id'];
$paymentInfo = $paymentProvider->getPayment($paymentId);
$status = $paymentInfo->getStatus();
 
// Perform actions in here to update your system
if ($status === 'paid') {
    ..
}
elseif ($status === 'cancelled') {
    ..
}

我們的 webhook URL 無(wú)法通過(guò)互聯(lián)網(wǎng)訪(fǎng)問(wèn)（請(qǐng)記住它：webhook.example.vagrant）。因此，PSP 永遠(yuǎn)不可能調(diào)用文件 webhook.php，你的系統(tǒng)將永遠(yuǎn)不會(huì)知道付款狀態(tài)，這最終導(dǎo)致訂單永遠(yuǎn)不會(huì)被運(yùn)送給客戶(hù)。

幸運(yùn)的是，ngrok 可以解決這個(gè)問(wèn)題。 ngrok 將自己描述為：

ngrok 通過(guò)安全隧道將 NAT 和防火墻后面的本地服務(wù)器暴露給公共互聯(lián)網(wǎng)。

讓我們?yōu)槲覀兊捻?xiàng)目啟動(dòng)一個(gè)基本的隧道。在你的環(huán)境中（在你的系統(tǒng)上或在 VM 上）運(yùn)行以下命令：

ngrok http -host-header=rewrite webhook.example.vagrant:80

閱讀其文檔可以了解更多配置選項(xiàng)：https://ngrok.com/docs。

會(huì)出現(xiàn)這樣的屏幕：

ngrok 輸出

我們剛剛做了什么？基本上，我們指示 ngrok 在端口 80 建立了一個(gè)到 http://webhook.example.vagrant 的隧道。同一個(gè) URL 也可以通過(guò) http://39741ffc.ngrok.io 或 https://39741ffc.ngrok.io 訪(fǎng)問(wèn)，它們能被任何知道此 URL 的人通過(guò)互聯(lián)網(wǎng)公開(kāi)訪(fǎng)問(wèn)。

請(qǐng)注意，你可以同時(shí)獲得 HTTP 和 HTTPS 兩個(gè)服務(wù)。這個(gè)文檔提供了如何將此限制為 HTTPS 的示例：https://ngrok.com/docs#bind-tls。

那么，我們?nèi)绾巫屛覀兊?webhook 現(xiàn)在工作起來(lái)？將 payment.php 更新為以下代碼：

<?php
/*
 * This file creates a payment and tells the PSP what webhook URL to use for updates
 * After creating the payment, we get a URL to send the customer to in order to pay at the PSP
 */
$payment = [
    'order_id' => 123,
    'amount' => 25.00,
    'description' => 'Test payment',
    'redirect_url' => 'http://webhook.example.vagrant/redirect.php',
    'webhook_url' => 'https://39741ffc.ngrok.io/webhook.php',
];
 
$payment = $paymentProvider->createPayment($payment);
header("Location: " . $payment->getPaymentUrl());

現(xiàn)在，我們告訴 PSP 通過(guò) HTTPS 調(diào)用此隧道 URL。只要 PSP 通過(guò)隧道調(diào)用 webhook，ngrok 將確保使用未修改的有效負(fù)載調(diào)用內(nèi)部 URL。

如何監(jiān)控對(duì) webhook 的調(diào)用？

你在上面看到的屏幕截圖概述了對(duì)隧道主機(jī)的調(diào)用，這些數(shù)據(jù)相當(dāng)有限。幸運(yùn)的是，ngrok 提供了一個(gè)非常好的儀表板，允許你檢查所有調(diào)用：

我不會(huì)深入研究這個(gè)問(wèn)題，因?yàn)樗遣谎宰悦鞯?，你只要運(yùn)行它就行了。因此，我將解釋如何在 Vagrant 虛擬機(jī)上訪(fǎng)問(wèn)它，因?yàn)樗皇情_(kāi)箱即用的。

儀表板將允許你查看所有調(diào)用、其狀態(tài)代碼、標(biāo)頭和發(fā)送的數(shù)據(jù)。你將看到應(yīng)用程序生成的響應(yīng)。

儀表板的另一個(gè)優(yōu)點(diǎn)是它允許你重放某個(gè)調(diào)用。假設(shè)你的 webhook 代碼遇到了致命的錯(cuò)誤，開(kāi)始新的付款并等待 webhook 被調(diào)用將會(huì)很繁瑣。重放上一個(gè)調(diào)用可以使你的開(kāi)發(fā)過(guò)程更快。

默認(rèn)情況下，儀表板可在 http://localhost:4040 訪(fǎng)問(wèn)。

虛擬機(jī)中的儀表盤(pán)

為了在 VM 中完成此工作，你必須執(zhí)行一些額外的步驟：

首先，確?？梢栽诙丝?4040 上訪(fǎng)問(wèn) VM。然后，在 VM 內(nèi)創(chuàng)建一個(gè)文件已存放此配置：

web_addr: 0.0.0.0:4040

現(xiàn)在，殺死仍在運(yùn)行的 ngrok 進(jìn)程，并使用稍微調(diào)整過(guò)的命令啟動(dòng)它：

ngrok http -config=/path/to/config/ngrok.conf -host-header=rewrite webhook.example.vagrant:80

盡管 ID 已經(jīng)更改，但你將看到類(lèi)似于上一屏幕截圖的屏幕。之前的網(wǎng)址不再有效，但你有了一個(gè)新網(wǎng)址。 此外，Web Interface URL 已更改：

現(xiàn)在將瀏覽器指向 http://webhook.example.vagrant:4040 以訪(fǎng)問(wèn)儀表板。另外，對(duì) https://e65642b5.ngrok.io/webhook.php 做個(gè)調(diào)用。這可能會(huì)導(dǎo)致你的瀏覽器出錯(cuò)，但儀表板應(yīng)顯示正有一個(gè)請(qǐng)求。

最后的備注

上面的例子是偽代碼。原因是每個(gè)外部系統(tǒng)都以不同的方式使用 webhook。我試圖基于一個(gè)虛構(gòu)的 PSP 實(shí)現(xiàn)給出一個(gè)例子，因?yàn)榭赡芎芏嚅_(kāi)發(fā)人員在某個(gè)時(shí)刻肯定會(huì)處理付款。

請(qǐng)注意，你的 webhook 網(wǎng)址也可能被意圖不好的其他人使用。確保驗(yàn)證發(fā)送給它的任何輸入。

更好的的，可以向 URL 添加令牌，該令牌對(duì)于每個(gè)支付是唯一的。只有你的系統(tǒng)和發(fā)送 webhook 的系統(tǒng)才能知道此令牌。

祝你測(cè)試和調(diào)試你的 webhook 順利！

注意：我沒(méi)有在 Docker 上測(cè)試過(guò)本教程。但是，這個(gè) Docker 容器看起來(lái)是一個(gè)很好的起點(diǎn)，并包含了明確的說(shuō)明：https://github.com/wernight/docker-ngrok 。