Setting up Hooks

Hooks are a common tool to communicate when an event happens to a subscribed platform. It sends an automated message to a server or email providing an automated form of communication between two systems.

Why use hooks?

Subscribing to hooks in Truora will help you to receive updates about the progress of checks, validations and other asynchronous processes. This is useful as you won't have to poll an endpoint to keep track of the statuses of these asynchronous processes, or enter the platform to check the status of each process. As a result, using hooks in your integration may simplify your process and potentially save time and money.

What events are notified via Hooks?

Each product has several events that can be notified via hooks. These events are as follows:

Product Events notified
Check When a check is created, started, or finished
Continuous Check When the score of the check has changed
Signals When an anomaly is detected, when an agent is reported or reactivated
Digital Identity When an identity process is created, or when the process has succeeded, failed or expired
Validations Events sent via hooks depend on the validator you use from the validator suite

You can choose what Products and events the hook will be subscribed to.

How hooks are notified?

There are 2 alternatives to receive the notifications of the events. In the moment of subscription you will have to choose one of these two types of hooks:

Via Email

For this type of hook, you will receive an email with the updates of the product/events that your hook is subscribed to.

Via Web

This type of notification, also known as webhooks, will be done by performing an HTTP POST request to the endpoint you provide. This request’s body will contain the information related to the event being notified.

Please note that this information will be sent in the request as a JWT (Json web token). This is a compact and self-contained way to transmit information securely between two parties in the form of a JSON object.

How to decode the JWT?

To parse the received token we are going to use the jwt.Parse(...) function, which expects the token as the first argument and a verification function as the second argument, where you will check that both the signing algorithm and the secret obtained from parsing the token are the expected ones. (otherwise you will know that the token has been altered).

As you can see in the example below, the jwt.Keyfunc function will allow you to make the pertinent validations on the token in question. This function will be used by the jwt.Parse method to detect possible alterations during such parsing.

For example:

receivedToken := "xxxxx.yyyyy.zzzzz"

token, err := jwt.Parse(receivedToken, func(token *jwt.Token) (interface{}, error) {
    if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
        return nil, fmt.Errorf("Unexpected signing method: %v", token.Header["alg"])
    }

    return mySecret, nil
})

Once parsed, we will have the jwt.Token and we will also have verified that said token was not maliciously altered. At this time you will only need to make a type assertion to the type of claims that we have used to obtain the claims contained by the token.

if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
    fmt.Println(claims["email"], claims["birthday"])
} else {
    fmt.Println(err)
}

And in this way, you will already be able to use the JSON Web Token (JWT) in your application.

Error handling

Webhooks notifications can be sent to invalid or inactive URLs without Truora or you realizing it. This is a problem because it can represent a security problem for you if Truora sends information indefinitely and you stop using that url, someone can use it and reach that information.

If you're responding with errors, we won't keep sending events to your servers forever. When your application enters any combination of these failure conditions for more than 80% of delivery attempts within 60 minutes, your application's event subscriptions will be disabled.

We'll also send to the Webhook's creator and owner, an email alerting you to the situation. You'll have the opportunity to re-enable deliveries when you're ready.