Validating Webhook Signatures from Kudosity

Your web application should verify that Kudosity is the service that sent a webhook before responding to that request. This is important for securing sensitive data, and to protect your application and servers from abuse.

Kudosity will sign callbacks to your application with an x-transmitsms-signature HTTP header.

Header Details:

The x-transmitsms-signature header contains an SHA-256 hash, created using the parameters returned in the callback and the account’s API secret as the encryption salt.

Test PHP Script

Below is a sample PHP script that demonstrates how the hash is constructed, enabling customers to replicate the process in their applications. This script can serve as a guide for building a module to verify the x-transmitsms-signature against query string parameters and the API secret, and thereby validate and secure your webhooks.

<?php
$params = [
  'message_id' => 'example_message_id',
  'mobile' => 'example_mobile_number',
  'datetime' => 'example_datetime',
  'status' => 'delivered',
  'user_id' => 'example_user_id',
  'rate' => 10,
];

$builturl = "https://example-url.com";
$builturl .= (strpos($builturl, '?') ? '&' : '?') . http_build_query($params);
$secret = 'your_api_secret';

echo "URL: {$builturl}\n";
$query = parse_url($builturl, PHP_URL_QUERY);
parse_str($query, $hashparams);
$json = json_encode($hashparams);

echo "JSON: {$json}\n";
$hash = hash_hmac('sha256', $json, $secret);
echo "Generated Hash: {$hash}\n";
?>

Note:
When generating the hash, ensure that parameters are in the exact order they appear in the callback. Any deviation in parameter order will result in a different hash.

Additionally, if using tools like Webhook.site, be aware that such tools may reorder parameters before displaying results, which can cause discrepancies in the generated hash.

Usage Instructions:

1. Replace the placeholder values in $params with the actual query string parameters returned in the callback.
2. Set the $builturl to the webhook’s target URL.
3. Set $secret to the API secret found in the account settings.

Sample Delivery Receipt (DLR) Callback:

Example Send

Captured DLR callback on Webhook.site

Sample Output

x-transmitsms-signature: 27b6822a9014c87da728cd510d51c7731464f59274fddc4e14959df712956f72

URL: https://webhook.site/fdf0e2c2-c4bb-42d4-8405-0ab90e16aec9?message_id=483979011&mobile=XXXXXXX&datetime=2021-04-26+04%3A18%3A00&status=delivered&user_id=XXXXXXX&rate=10
array(6) {
  ["message_id"]=>
  string(9) "483979011"
  ["mobile"]=>
  string(11) "61429859724"
  ["datetime"]=>
  string(19) "2021-04-26 04:18:00"
  ["status"]=>
  string(9) "delivered"
  ["user_id"]=>
  string(5) "63935"
  ["rate"]=>
  string(2) "10"
}
JSON: {"message_id":"483979011","mobile":"XXXXXXXXX","datetime":"2021-04-26 04:18:00","status":"delivered","user_id":"XXXXXX","rate":"10"}
Built: 27b6822a9014c87da728cd510d51c7731464f59274fddc4e14959df712956f72