Description

If an address was specified in the callbackUrl field when creating a conversation, it will be called when the specified events occur.

The test environment allows the use of an HTTP address. A production environment always requires HTTPS.
For testing purposes, to check the callback request, you can use online tools that accept and present the outgoing requests. One such tool is, for example, Weebhook. When creating a conversation, it is enough to provide the url generated by Weebhook in the callbackUrl parameter.

Description of sent data

Authologic sends data by calling the POST method to the HTTPS address defined when creating the conversation. The server should respond with a status of 200, 201 or 202. Any other answer will try to retry. Such attempts will take place several times in the growing recesses of time. Currently, it is 20 attempts over 4 days.

The content of the request is as follows:

Callback: Sample data structure
{
    "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 chapter.

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.

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