Webhook Overview

The webhook API allows your application to be informed with the latest events occurring in the commerce platform. Rather than your application making API calls every x minutes to the commerce platform to check if a specific event occurs, you can subscribe for a webhook with a callback URL for specific events in the commerce platform. When the event occurs within the commerce platform, a JSON message will be posted to your callback URL.

Securing Webhook

The platform uses the industry standard HMAC-SHA256 encryption to secure the webhook.
Here are the steps:
  • Developer creates a webhook by supplying a shared secret in the Create Webhook API.
  • Before the platform sends the Webhook event to the Developer's Callback URL, it will include a based-encoded HMAC-SHA256 header called X-Fdx-Sc-Signature (this parameter name is a placeholder) in the HTTP request. The X-Fdx-Sc-Signature is generated by the data sent in the request and the shared secret.
  • The callback URL specified by the developer needs to verify that the request is indeed coming from the FedEx platform. The developer's web application can compute the HMAC digest from the data in the request and the shared secret and compare it to the value from in the X-Fdx-Sc-Signature header. If both match, the developer can then be sure that the request is from the FedEx Supply Chain platform and the data are not compromised.

Same Code in PHP:

<?php 
define('SHARED_SECRET', 'my_shared_secret');
function verify_webhook($data, $hmac_header)
{
    $calculated_hmac = base64_encode(hash_hmac('sha256', $data, SHARED_SECRET, true));
    return hash_equals($hmac_header, $calculated_hmac);
}
$hmac_header = $_SERVER['HTTP_X_FDX_SC_SIGNATURE'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);
error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result
?>