# Callbacks 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. They can also be used to receive other information. 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 via the `callbackUrl` property, e.g .: ```shell 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://id.sandbox.authologic.com/c/{conversationId}/thankYou", "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](https://webhook.site/). When creating a conversation, it is enough to provide the url generated by Webhook in the `callbackUrl` parameter. ## Description of Sent Data The server must respond with one of the HTTP statuses: `200`, `201`, `202` or `204`. Otherwise, the notification will be considered unsuccessful and the system will attempt to resend the information. Such attempts will take place several times in the increasing time intervals. The first attempt is made immediately after a failed delivery. The number of attempts depends on various factors and is adjusted automatically, but it is guaranteed that at least 20 attempts will be made and that the final attempt will occur no sooner than after 4 days. Thanks to this, in the event of a temporary unavailability, data has a chance to be delivered. The content of the request is as follows: ```json { "id": "02eb1705-fe8f-4d3d-b768-f48b06d26a7e", "created": "2020-09-17T11:18:21.999Z", "target": "...", "event": "...", "payload": { "...": {} } } ``` Description of individual fields:
Parameter Example Description
id 02eb1705-fe8f-4d3d-b768-f48b06d26a7e Unique identifier for the event. If the event is sent multiple times, the identifier is the same. The receiving system should make a possible omission of duplicates.
created 2020-09-17T11:18:21.999Z Date when the event occurred.
target CONVERSATION The object that generated the event.
event FINISHED The type of the event.
payload Any objects that describe current specific event. For each type of event payload may have a different structure.
Authologic also sets the following HTTP headers:
Header Value
Content-Type application/json;charset=UTF-8
X-Signature
X-Signature-Timestamp
The `X-Signature` and `X-Signature-Timestamp` headers are used to verify the sender of a message and are described later in this document. ## Event types The following events are currently available:
Target Event Data available Description
CONVERSATION FINISHED conversation Information about the end of the conversation and the verification status. In this case, the payload field contains the conversation object with details of the completed conversation.
CONVERSATION EXPIRED conversation Information about expiration of the conversation. In this case, the payload field contains the conversation object with details of the completed conversation.
SUBSCRIPTION NEW_DATA conversation Information about new data related to the subscription associated with the conversation. In this case, the payload field contains the conversation object with updated information about the found AML lists.
## 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: ```json { "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" } } } } } } } } ``` As a best practice, we recommend implementing your system to handle callback payloads that may include additional fields not known during development. You may choose to ignore these extra fields, but we strongly advise against overly strict parsing of the callback payload body. 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 has 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. For example, a conversation in which you asked for user verification and for downloading of user's banking transactions. Authologic may 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`. > #### Conversation Identifier vs Callback Identifier > > Please note, that in the above response the top level identifier is the **callback** identifier, not the > **conversation** identifier. In order to retrieve metadata about the conversation using Authologic APIs, > you should use the **conversation** identifier, which is the **id** field value that is located in > the **payload.conversation** object. 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: `:`. 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. ## Callback forward compatibility testing In order to test the forward compatibility of the callback, you should: 1. Make sure callback processing mechanism is prepared to receive a callback with a payload that contains additional fields not described in the current version of the API. 2. Make sure all unknown fields in the callback payload are ignored. The integration verification procedure involves simulating a callback notification with random fields in the payload. The presence of random fields should not cause any issues with receiving the callback notification. 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](mailto:tech-support@authologic.com)