Securing Webhooks

When registering your Webhook, you can provide an optional secret value to ensure that calls to your endpoint originate from Field Nation.

Create a Secure Webhook

To include a secret value in a Webhook definition:

{
    "url": "https://yourcompany.com/handle_webhook",
    "secret": "abcde42a8f6c09545b3bedbe2ab45a50"
    "method": "POST",
    "active": true,
    "events": ["workorder.created"]
}

Verify Requests to Your Endpoint

Each call to your endpoint will include a Fn-Hash in the request Header, which is an md5 hash of your secret value and the HTTP request body.

Fn-Hash: 2c1d518109f33401203114546bb8ab85
Content-Length: 24241
Via: 1.1 174575cecfe8d496e19c0d2e2f440eb4.cloudfront.net (CloudFront), 1.1 vegur
Connect-Time: 1
Content-Type: application/json
Connection: close
Accept: application/json
Cloudfront-Is-Desktop-Viewer: true
Cloudfront-Forwarded-Proto: http
Cloudfront-Viewer-Country: US
X-Request-Id: fc3c6f6d-d4fd-4bef-a410-b74bd8494c06
Cloudfront-Is-Mobile-Viewer: false
X-Amz-Cf-Id: YeM4yURtQ1wgV3IB9xJJTEM9j217z7gEZb4HsFN9sXIUv_q5sozQNw==
Cloudfront-Is-Tablet-Viewer: false
Cloudfront-Is-Smarttv-Viewer: false

You can use this md5 hash to verify the request from Field Nation.

$fnHash = "2c1d518109f33401203114546bb8ab85"; // from webhooks header fn-hash
$mySecret = "abcde42a8f6c09545b3bedbe2ab45a50";
$body = "{\r\n\t\"url\": \"https://yourcompany.com/handle_webhook\",
\r\n\t\"secret\": \"abcde42a8f6c09545b3bedbe2ab45a50\",\r\n\t\"method\": \"POST\",\r\n\t\"active\": true,\r\n\t\"events\": [\r\n\t\t\"workorder.created\",\r\n\t]\r\n}"

$expectedHash = md5($mySecret . $body); 

if ($expectedHash !== $fnHash) {
    echo "unable to verify";
}