Callbacks

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 .:

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"]
            ]
        }
    }
}'

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:

{
  "id": "02eb1705-fe8f-4d3d-b768-f48b06d26a7e",
  "created": "2020-09-17T11:18:21.999Z",
  "target": "...",
  "event": "...",
  "payload": {
    "...": {}
  }
}

Description of individual fields:

Authologic also sets the following HTTP headers:

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:

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.

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: <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.

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.