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
Checks	created started finished delayed
Continuous Checks	changed
Signals	detected
Digital Identity	expired created succeeded failed
Document Validation	created succeeded failed
Email Validation	created succeeded failed
Enterprise Data Validation	created succeeded failed
Facial Recognition	created succeeded failed
TruFace	created succeeded failed
Identity Questions	created succeeded failed
Phone Validation	created succeeded failed
Voice Recognition	created succeeded failed
Whatsapp Inbound	started
Whatsapp Outbound	started canceled approved
Whatsapp Session	started expired canceled restarted
Whatsapp Process	started succeeded failed

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 HTTPS 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, the system will try to send the notification a total of 5 times with an exponential backoff delay. 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.

Retry	Delay
1	30 sec
2	2 min
3	8 min
4	32 min
5	128 min

Failure modes

Because webhook notifications are asynchronous, we recommend implementing a fallback logic in case you experience any delivery delays that could affect your users experience. Alternatively, you can use the GET endpoint of the resource to obtain the most recent changes.

• Call the GET endpoint of the resource you are interested in using the ID obtained.
• Check the status field in the response to find out the current status of the resource. For example, "status": "success".

On the other hand, if you are using the GET /events endpoint as well as webhooks to process events, there is a chance to process the same event multiple times. Although this is a rare occurrence, we recommend that systems processing webhooks events do this in a manner that anticipates duplicates and deals with them appropriately.

To do this, save the event idempotency key, and when a new event is received, discard it if it already exists.