From 8e833eca04884a1c39098d5c396e29eb969ec3f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Mattrat?= <felix@messagebird.com>
Date: Tue, 5 Oct 2021 17:33:41 +0200
Subject: [PATCH] Update readme with up-to-date webhook signature doc

---
 README.md | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 73135e5..dc27242 100644
--- a/README.md
+++ b/README.md
@@ -106,24 +106,49 @@ Messaging and Voice API use different pagination semantics:
 Verifying Signatures
 -------------
 
-We sign our HTTP requests to allow you to verify that they actually came from us (authentication) and that they haven't been altered along the way (integrity). For each HTTP request that MessageBird sends, a `MessageBird-Signature` and `MessageBird-Request-Timestamp` header is added. Signature middleware calculates a signature using the timestamp, query parameters and body then compares the calculated signature to `MessageBird-Signature` header. If they are not same or request expired, middleware throws an error. This way, you will know if the request is valid or not. If you want to verify request manually, you can check [here](https://developers.messagebird.com/docs/verify-http-requests). Let's use Signature middleware to verify webhooks.
+For each HTTP request that MessageBird sends, a `MessageBird-Signature-JWT` header is added.
+
+The `MessageBird-Signature-JWT` header is a signature that consists of all the information that is required to verify the integrity of the request. The signature is generated from the request URL and request body and is signed with the HMAC-SHA256 algorithm using your your signing key. You can validate this signature using our SDKsto e nsure that the request is valid and unaltered. The token also includes timestamp claims that allow you to prove the time of the request, protecting from replay attacks and the like. 
+For more details consult the [documentation](https://developers.messagebird.com/api/#verifying-http-requests). 
+
+Examples:
+- [full example with Express](./examples/webhook-signature-express-middleware.js)
+- [example in vanilla JS](./examples/webhook-signature-http-node.js)
+
+
+Let's use Express Signature middleware to verify webhooks.
 
 ```javascript
-var Signature = require('messagebird/lib/signature');
+// This example show how to verify the authenticity of a MessageBird webhook.
+const mbWebookSignatureJwt = require('messagebird/lib/webhook-signature-jwt');
+const express = require('express');
+
+const secret = '<YOUR SIGNING KEY>';
+
+const app = express();
+
+// If the node server is behind a proxy, you must trust the proxy to infer the correct protocol and hostname.
+
+app.set('trust proxy', () => true);
 
 // Replace <YOUR_SIGNING_KEY> with your actual signing key.
-var verifySignature = new Signature('<YOUR_SIGNING_KEY>');
+const verifySignature = new mbWebookSignatureJwt.ExpressMiddlewareVerify(secret);
 
 // Retrieve the raw body as a buffer.
-app.use(require('body-parser').raw({ type: '*/*' }));
+app.use(express.raw({ 'type': '*/*' }));
 
 // Verified webhook.
-app.get('/webhook', verifySignature, function(req, res) {
-    res.send("Verified");
+app.get('/webhook', verifySignature, (req, res) => {
+  res.send('verified');
+});
+app.post('/webhook', verifySignature, (req, res) => {
+  res.send('verified');
 });
-
 ```
 
+
+
+
 Documentation
 -------------