article Securing Webhooks

Webhooks are a powerful way to receive real-time updates from GoFreight FMS. However, they can also be vulnerable to attacks or unauthorized access if not properly secured. One common method to secure webhooks is by using HMAC (Hash-based Message Authentication Code) signatures. This article will show you how to use HMAC signatures to verify the authenticity of webhook requests from GoFreight.

How to retrieve the secret token? link

When you create a webhook subscription via API¹, you will be given an auto-generated secret in the response (an example is shown below). You can also retrieve the secret of an existing subscription by sending a GET request to the endpoint /api/v1/webhook/{ref}/².

{
    "data": {
        "ref": "926a3c25-d1e2-4ee6-a303-405a66ede284",
        "callback_url": "https://example.com/callback/",
        "event_types": ["INVOICE_BLOCK_STATUS_UPDATED"],
        "secret": "Tr5Tkf8wRHsvWiZt",
        "description": "foobar",
        "enabled": true,
        "created_at": "2023-09-08T09:51:42.899365Z",
        "updated_at": "2023-09-08T09:51:42.899336Z"
    }
}

The secret token is used to generate the HMAC signature for each webhook event payload, which will be explained in the next section.

Validate Event Payload from GoFreight link

GoFreight uses the secret token to create a HMAC signature with SHA-256 algorithm for each webhook event payload. The signature is included in the x-gofreight-signature header of each webhook request. To verify that if the event payload is from GoFreight, you’ll need to follow these steps:

1. Retrieve the webhook subscription by the reference ID included in the x-gofreight-webhook-subscription-ref header of the webhook event request.
2. Retrieve the secret token of the webhook subscription.
3. Parse the event payload from the request body.
4. Generate a signature using the secret token and the event payload.
5. Compare the generated signature with the signature from the request header.

Your language and server implementations might vary from the following examples. Nevertheless, it’s crucial to highlight several key points:

• GoFreight provides the x-gofreight-signature header values in the format of {timestamp}.{hashed_payload}, where the timestamp is used to prevent replay attacks. You can optionally drop the request if the timestamp is too old (e.g. older than 5 minutes).
• Using equality operators (e.g. ==) for comparing signatures is not recommended. Use JavaScript’s crypto.timingSafeEqual or Python’s hmac.compare_digest instead to reduce the risk of timing attacks.

Here are some examples of how to verify the signature in different languages:

import hashlib
import hmac
import json

def verify_webhook_hmac_signature(secret: str, payload: dict, signature_header: str) -> bool:
    """Verify the HMAC signature of the webhook payload.

    Args:
        secret (str): The secret token of the webhook subscription.
        payload (dict): The payload of the webhook event (`request.body()`).
        signature_header (str): The signature received from the webhook request.

    Returns:
        bool: True if the signature is valid, False otherwise.
    """
    ts, sig = signature_header.split('.')

    payload_json_str = json.dumps(payload, separators=(',', ':'), sort_keys=True)
    secret_bytes = secret.encode('utf-8')

    payload_bytes = f'{ts}.{payload_json_str}'.encode()
    hmac_obj = hmac.new(secret_bytes, msg=payload_bytes, digestmod=hashlib.sha256)
    return hmac.compare_digest(hmac_obj.hexdigest(), sig)

const crypto = require('crypto');

function verifyWebhookHmacSignature(secret, payload, signatureHeader) {
  const [ts, sig] = signatureHeader.split('.');

  const sortedPayload = Object.fromEntries(Object.entries(payload).sort());
  const payloadJson = JSON.stringify(sortedPayload, null, 0);

  const secretBuffer = Buffer.from(secret, 'utf-8');
  const payloadBuffer = Buffer.from(`${ts}.${payloadJson}`, 'utf-8');

  const hmacObj = crypto.createHmac('sha256', secretBuffer);
  hmacObj.update(payloadBuffer);
  return crypto.timingSafeEqual(
    Buffer.from(hmacObj.digest('hex'), 'utf-8'),
    Buffer.from(sig, 'utf-8')
  );
}

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/json"
	"fmt"
	"strings"
)

func verifyWebhookHMACSignature(secret string, payload map[string]interface{}, signatureHeader string) bool {
	parts := strings.Split(signatureHeader, ".")
	if len(parts) != 2 {
		return false
	}
	ts, sig := parts[0], parts[1]

	payloadJSON := marshalPayload(payload)
	payloadBytes := []byte(ts + "." + payloadJSON)

	hmacObj := hmac.New(sha256.New, []byte(secret))
	hmacObj.Write(payloadBytes)
	return hmac.Equal([]byte(hex.EncodeToString(hmacObj.Sum(nil))), []byte(sig))
}

// Helper function to marshal the payload into a JSON string
func marshalPayload(payload map[string]interface{}) string {
	payloadJSON, err := json.Marshal(payload)
	if err != nil {
		return ""
	}
	return string(payloadJSON)
}