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 -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:
{
"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, 202 or 204. 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, 202 or 204 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:
-
Check that the timestamp given in the HTTP header
X-Signature-Timestampdoes 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) -
Execution of the cryptographic hash function
HMAC_SHA_256on the string built according to the scheme:<X-Signature-Timestamp>:<Response content>. The signature key provided by Authologic must be used as the key. -
Compare
X-Signaturewith 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