什麽是 Webhook Signature

What and Why

在串接对方 webhooks 时通常会看到文件上提到 signature「签章」，可以感觉的到它应该跟验证或什麽安全有关，但详细到底怎麽运作呢？

其实签章的概念很简单，用信件来比喻的话，就是让收信方能验证这封信是真的出自他认识的人，而非伪造的。所以当我们收到信时，就必须先检查这封信上的签名是否依据我们私下约定好的方式签写，比方说签完名要多画一颗爱心。而当有心人士想伪造假信寄给我们时，他也许知道要伪造签什麽名，但他不知道签完还要画爱心，这样收信的我们就能识破没有爱心的信是假的了。

回到 webhook signature，其实也是一样的，收送双方需要先约定好两样不让外人知道的东西：签什麽名(content)、和要多画什麽图(secret)。以以下 HTTP request 为例，我们可以约定好 message 内容接 timestamp 在後头是 content，而 secret 是 draw_a_heart，以HMAC-SHA256加密，最後把做好的签章也放在 body 里。

POST /my/webhook/endpoint HTTP/1.1
Host: my.web
Content-Type: application/json

{
    "signature": "b18dcf385031a45c0e7f805a50f6ac3d8799d702072c4b79cd9a1d026cf8ecd4"
    "timestamp": 1631634099,
    "message" : "Gawr Gura is the best <3"
}

所以我们收到信後可以拿 message 和 secret 去产生签证，再跟我们收的签章做比对，就知道讯息是否来自约定的对方了。

以 PHP 为例

/**
*
* @return boolean 验证成功回传 true，失败回传 false
*
*/
function verify($request)
{
    return $request->signature === hash_hmac(
        'sha256',
        $request->message . $request->timestamp,
        $secret
    );
}

可以用线上工具验证看看 Online hash tool

practice

• HMAC-SHA256 Online Generator Tool
• 用于消息验证的hash算法HMAC
• hash_hmac