The purpose of the document is to provide information about the mechanism of informing about events in the system in the context of the verification performed. We assume knowledge of the information contained in the documents Scheme of operation and Integration in 5 minutes: Basic information. The mechanism also allows you to receive information about other events in the system. More information is available from here.

In the basic API, it is possible to query the current conversation status using the GET /api/conversations/{conversationId} method. In practice, the time after which the conversation status will change is not strictly defined and depends on the selected verification method and user actions. Sometimes the verification is immediate, sometimes it takes several minutes and sometimes several days. It can also be abandoned by the user. Asking for a conversation every specified period of time is not very convenient, if only because of the problem with the right choice of this time, which is why Authologic provides a change notification mechanism, the so-called callback.

Callback address declaration

The declaration of the use of this mechanism is simple. When creating a conversation add the address to which we want to receive notifications, e.g .:

curl
curl -X POST -u my_login "https://sandbox.authologic.com/api/conversations" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json" \
-d '{
    "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
    "returnUrl": "https://authologic.com/tests/return/?conversation={conversationId}",
    "callbackUrl": "https://authologic.com/tests/callback/?conversation={conversationId}&target={target}&event={event}",
    "query": {
        "identity": {
            "requireOneOf": [
                [ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
            ]
        }
    }
}'
For testing purposes, to check the callback request, you can use online tools that accept and present the requests that are sent. One such tool is, for example, Webhook. When creating a conversation, it is enough to provide the url generated by Webhook in the callbackUrl parameter.

An example of a callback about a finished conversation

As soon as the conversation is finished (regardless of the result), Authologic will send information about the status of the conversation to the specified address using the POST method. An example of the call content for the case when the conversation succeeded in obtaining user data is as follows:

Callback: Example of data returned
{
    "id": "02eb1705-fe8f-4d3d-b768-f48b06d26a7e",
	"created": "2020-09-17T11:18:21.999Z",
	"target": "CONVERSATION",
	"event": "FINISHED",
	"payload": {
		"conversation": {
            "id":"e0c0b3cc-8238-414f-9940-9f14bd1b8693",
            "userKey":"d5dbb8e0-192e-4bc6-972c-f7948409d10c",
            "url":"https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
            "status":"FINISHED",
            "result":{
                "identity":{
                    "status":"FINISHED",
                    "user":{
                        "person":{
                            "name":{
                                "firstName":"Jan",
                                "lastName":"Testowy"
                            }
                        }
                    }
                }
            }
        }
    }
}

The content of the payload.conversation field is analogous to the response with conversation details.

The server must respond with one of the HTTP statuses: 200, 201 or 202. Otherwise, the notification will be considered unsuccessful and will attempt to resend the information. Such attempts will take place several times in the growing recesses of time. Thanks to this, in the event of a temporary unavailability, data have a chance to be delivered.
If it gets different values of target and event, the system should accept a callback, responding with HTTP status 200, 201 or 202 and then ignore it. Thanks to this, the system will be resistant to possible events implemented in the future.
In some cases, Authologic will be able to send an update after acquiring some data. An example is, for example, a conversation in which you asked for user verification and for downloading his banking transactions. Authologic maybe then send one notification: after finishing the conversation, it can also send two: one after getting user data and the other after preparing the transaction data. It’s up to you to decide whether to process both information independently or to wait on the second, final call, where the status field is` FINISHED`.

The use in the address {conversationId}, {target} and {event} is optional and, if present, will be replaced with the conversation ID, the name of the event generating object and the event type, respectively.

Verification of the message sender

When receiving a callback, you should make sure that its content is from Authologic and has not been tampered with by anyone. For this purpose, we provide a sender verification mechanism. The sender should be verified using the contents of the HTTP headers named X-Signature and` X-Signature-Timestamp` and the signature key provided by Authologic.

The verification algorithm is as follows:

  1. Check that the timestamp given in the HTTP header X-Signature-Timestamp does not differ from the current one by more than 5 minutes. Timestamp is presented as a number of milliseconds since UNIX epoch (January 1, 1970 00:00:00 UTC)

  2. Execution of the cryptographic hash function HMAC_SHA_256 on the string built according to the scheme: <X-Signature-Timestamp>:<Response content>. The signature key provided by Authologic must be used as the key.

  3. Compare X-Signature with the result

Example

The following example may be useful to test the signing algorithm:

  • Signature key: dey6TaePhiogi7ohgiek0pho

  • Timestamp: 1641046369772

  • Query content (note the whitespaces): { "test": true }

  • SHA256 is calculated with the inscription: 1641046369772:{ "test": true }

  • generated signature: fb96c41afe39c6b1cb9377a63405f9f072c1ccf2f04b85fcaeda2c081dcabba6

Potential problems with the signature

In case of problems, make sure that:

  • you are using a specially designed key signature verification and not e.g. API key

  • Make sure that the content of the query is not changed by the framework you are using: e.g. JSON is not formatted

  • Check that the content of the query is treated by you as UTF-8

Despite our sincere intentions, it is difficult to create perfect technical documentation. If you have an idea on how to improve this documentation, or you have trouble understanding any section, please email us at tech-support@authologic.com