Events

With the webhook integration, you can decide to subscribe to different kinds of events.

Webhooks provide a powerful method to track the state of transactions and to take actions within your Fido account. Review these best practices to ensure your webhooks remain secure and function seamlessly with your integration.

The most common event you can subscribe to. It gets "fired" whenever Fido generates a new score. You can receive this event even in case the score gets updated.

v1-score

v1-score includes the score cluster and all information concerning the user document.
For more information about the data you can take a look at Digital Footprints

The format of the data is JSON and is described in the API reference here

Code Example

<?php
  
require 'vendor/autoload.php';

// Retrieve the request's body and parse it as JSON
$input = \file_get_contents("php://input");
$event = \json_decode($input, true);

if(isset($event['type']) && $event['type'] === "v1-score") {
  
  \print_r($event['score']); // ['value'=> 100, 'cluster'=> 'very_low']
  
}

Event types

Your webhook endpoints should be configured to receive only the types of events required by your integration. Listening for extra events (or all events) will put undue strain on your server and is not recommended.

Disable logic

Fido will attempt to notify you of a misconfigured endpoint via email if an endpoint has not responded with a 2xx HTTP status code for multiple days in a row.

Event handling

Handling webhook events correctly is crucial to making sure your integration’s business logic works as expected.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

Additional security

To ensure that the message comes from fido we always add a custom header to any webhook.

The header x-fido-signature contains a hashed/signed version of the payload, encoded in base64.

The algorithm used is the standard SHA256 OPEN SSL and can be verified using the following public key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Fb/W9KubpGIlU/zKdRA
xJFLRrBIZWdfSOifn0cqgVMcGEUCPREwJ/GGK/GChyRLDb5wGl9l4NHU1GcvoGgn
5at/i36jKNx7SMIaKwc4ShIMqWGj8CLGSTcQQ++UOTY0pwWlnoNPBXxuhsP6hsWp
6yUks6WxHYVPqp+3EFbfI0X5AgkwvA3I/pzctVmYBiDEG3dXyLIs4IcXwqx8AwPd
viB1WgXyfJl8bn0fOyKL/4NjUL/9xrTWE51SYiJltQxzeXcuCqkqhbuu284gsGbh
a5Y2EsTo5CwyLbFQdF4UFNV3lTYx4/zYKJpzLVODwTSOuNzlClDyqa2zXsTHdaW0
LwIDAQAB
-----END PUBLIC KEY-----

An example of the verify process:

<?php

$key = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Fb/W9KubpGIlU/zKdRA
xJFLRrBIZWdfSOifn0cqgVMcGEUCPREwJ/GGK/GChyRLDb5wGl9l4NHU1GcvoGgn
5at/i36jKNx7SMIaKwc4ShIMqWGj8CLGSTcQQ++UOTY0pwWlnoNPBXxuhsP6hsWp
6yUks6WxHYVPqp+3EFbfI0X5AgkwvA3I/pzctVmYBiDEG3dXyLIs4IcXwqx8AwPd
viB1WgXyfJl8bn0fOyKL/4NjUL/9xrTWE51SYiJltQxzeXcuCqkqhbuu284gsGbh
a5Y2EsTo5CwyLbFQdF4UFNV3lTYx4/zYKJpzLVODwTSOuNzlClDyqa2zXsTHdaW0
LwIDAQAB
-----END PUBLIC KEY-----
EOD;

// coming from the body of the request
$payload = '{"dummy":true}';

// an example of signed payload, coming from x-fido-signature
$header  = 'AIguVUqQf/ZH0j9yp/c+fkIxWAzxulEj5Atd7AxODm74K2o/Mo7t+my41o3yvf/cIizdMd/DslcOU1uE0GcxAn6Fj1SQpBmTIMiMJGINMYzmdy76yPuED45Rm6gm2CEGfqkRO7cl7EbqT/myfmdtTDf05S+Xoy3UxSRtS88/NTIUQfnrgLUZeAMDyn8e1F2mDtsVFlx1o/HIg3oQhuX/Su5dklmv+NMcwBQr+TUunrzBAUVdEKJQk/mh6QBnZj+ZCMEOOsA7K2dZVf/CN5nrOhegN6Yv9Vf7jUCnRwANZrX+kHBR2OvKqZD1zqYX9wt76K+GDm68ykIbBXNfxBUlNg==';

$isValid = \openssl_verify($payload, \base64_decode($header), $key, OPENSSL_ALGO_SHA256);

print_r($isValid); // 1
#!/bin/bash
# Verify a file with a public key using OpenSSL
# Decode the signature from Base64 format
#
# Usage: verify <file> <signature> <public_key>
#
# NOTE: to generate a public/private key use the following commands:
#
# openssl genrsa -aes128 -passout pass:<passphrase> -out private.pem 2048
# openssl rsa -in private.pem -passin pass:<passphrase> -pubout -out public.pem
#
# where <passphrase> is the passphrase to be used.

filename=$1
signature=$2
publickey=$3

if [[ $# -lt 3 ]] ; then
  echo "Usage: verify <file> <signature> <public_key>"
  exit 1
fi

openssl base64 -d -in $signature -out /tmp/$filename.sha256
openssl dgst -sha256 -verify $publ

Did this page help you?