Online paymentsWebhooks

Verifying the events

Overview

Webhooks carry a certain level of security risk, as malicious actors can attempt to send fake webhooks, posing as legitimate services. This can lead to security vulnerabilities and other undesired issues.

To ensure the authenticity of received events from Yoco, the following two actions are required:

  • Avoiding replay attacks
  • Validating the signature

Avoiding replay attacks

The webhook header contains a webhook-timestamp property that describes a Unix timestamp indicating when the webhook was signed.

This timestamp should be used to reduce the chance of replay attacks.

Because the timestamp is included in the header, the same header cannot be sent with a different timestamp without causing an invalid signature. When verifying the signature, you should also validate that the timestamp is within an acceptable threshold from your current system time (in Unix epoch format).

We recommend a threshold of up to 3 minutes.

If Yoco retries sending the webhook notification event, the timestamp at the time of sending the retried event is used, so each attempt would have a new timestamp and therefore a new hash.

Validating the signature

Events sent from our service contain the webhook-signature header. To ensure the webhook’s authenticity and confirm its origin from our service, follow the provided steps to compare a generated signature with the signature from the header.

1

Construct the signed content

To generate the signed content, concatenate the values of the webhook-id header, webhook-timestamp header, and the raw request body using a full stop (.) as a separator.

Node.js
1// Using Express
2
3const headers = req.headers;
4const requestBody = req.rawBody;
5
6const id = headers["webhook-id"];
7const timestamp = headers["webhook-timestamp"];
8
9const signedContent = `${id}.${timestamp}.${requestBody}`;
Python
1# Using Flask
2
3headers = request.headers
4request_body = request.get_data(as_text=True)
5
6id = headers.get('webhook-id')
7timestamp = headers.get('webhook-timestamp')
8
9signed_content = str(id) + '.' + str(timestamp) + '.' + str(request_body)

Make sure to use the raw request body in this step. Any minor modification to the body will generate a completely different signature.

2

Determine the expected signature

To calculate the expected signature, use the secret key and the signed content to generate a HMAC SHA256 signature. Then, encode this value using base64.

Node.js
1const crypto = require("crypto");
2
3const secret = "whsec_XXXXXXXXXXXXXXXXXXXXXXXXX=";
4const secretBytes = Buffer.from(secret.split("_")[1], "base64");
5
6const expectedSignature = crypto
7  .createHmac("sha256", secretBytes)
8  .update(signedContent)
9  .digest("base64");
Python
1import base64
2import hmac
3import hashlib
4
5# Using Flask
6secret = 'whsec_XXXXXXXXXXXXXXXXXXXXXXXXX='
7secret_bytes = base64.b64decode(secret.split('_')[1])
8
9hmac_signature = hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
10expected_signature = base64.b64encode(hmac_signature).decode()

Before calculating the expected signature, ensure that you exclude the whsec_ prefix from the secret key.

3

Compare signatures

The webhook-signature header consists of a list of signatures and their version identifiers, separated by spaces. Typically, the signature list consists of only one element, but it can contain any number of signatures.

For example:

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

Before verifying the signature, make sure to remove the version prefix and delimiter (e.g., v1,).

The generated signature should be compared with the signature sent in the webhook-signature header. If the generated signature matches the provided signature, you can proceed with processing the webhook event.

When comparing the signatures, it is recommended to use a constant-time string comparison method to prevent timing attacks.

Full example

Node.js
1const express = require("express");
2const crypto = require("crypto");
3const getRawBody = require("raw-body");
4
5const app = express();
6
7app.use((req, res, next) => {
8  getRawBody(
9    req,
10    {
11      length: req.headers["content-length"],
12      encoding: "utf-8",
13    },
14    (err, rawBody) => {
15      if (err) return next(err);
16      req.rawBody = rawBody;
17      next();
18    },
19  );
20});
21
22// Using Express
23app.post("/my/webhook/url", function (req, res) {
24  const headers = req.headers;
25  const requestBody = req.rawBody;
26
27  // Construct the signed content
28  const id = headers["webhook-id"];
29  const timestamp = headers["webhook-timestamp"];
30
31  const signedContent = `${id}.${timestamp}.${requestBody}`;
32
33  // Determine the expected signature
34  const secret = "whsec_XXXXXXXXXXXXXXXXXXXXXXXXX=";
35  const secretBytes = Buffer.from(secret.split("_")[1], "base64");
36
37  const expectedSignature = crypto
38    .createHmac("sha256", secretBytes)
39    .update(signedContent)
40    .digest("base64");
41
42  // Compare the signatures
43  const signature = headers["webhook-signature"].split(" ")[0].split(",")[1];
44  if (crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signature))) {
45    // process webhook event
46    return res.sendStatus(200);
47  }
48  // do not process webhook event
49  return res.sendStatus(403);
50});
51
52app.listen(3000, () => {
53  console.log("Server is running on port 3000");
54});
Python
1from flask import Flask, request
2import hashlib
3import base64
4import hmac
5
6app = Flask(__name__)
7
8# Using Flask
9@app.route('/my/webhook/url', methods=['POST'])
10def webhook():
11    headers = request.headers
12    request_body = request.get_data(as_text=True)
13
14    # Construct the signed content
15    id = headers.get('webhook-id')
16    timestamp = headers.get('webhook-timestamp')
17
18    signed_content = str(id) + '.' + str(timestamp) + '.' + str(request_body)
19
20    # Determine the expected signature
21    secret = 'whsec_XXXXXXXXXXXXXXXXXXXXXXXXX='
22    secret_bytes = base64.b64decode(secret.split('_')[1])
23
24    hmac_signature = hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
25    expected_signature = base64.b64encode(hmac_signature).decode()
26
27    # Compare the signatures
28    signature = headers.get('webhook-signature').split(' ')[0].split(',')[1]
29    if hmac.compare_digest(signature, expected_signature):
30        # process webhook event
31        return "", 200
32
33    # do not process webhook event
34    return "", 403
35
36if __name__ == '__main__':
37    app.run()