Skip to main content

Webhook

Updates to monitoring topics will be notified through webhook deliveries. To enable this, it is necessary to configure—through the support team—an endpoint address where we will send update notifications, as well as a signature_key that will be used to sign the request. It is important to note that all webhook deliveries will be sent to a single endpoint.

Attention

For security reasons, all Webhook requests will only be made to endpoints served over HTTPS.

Signature​

Example of signature calculation in Python

hmac_obj = hmac.new(
    signature_key.encode('utf-8'),
    (url + method + payload).encode('utf-8'),
    hashlib.sha1
)
return hmac_obj.hexdigest()

To ensure that the request received at the webhook endpoint originates from our servers, an HMAC signature is sent in the Signature header, similarly to the authentication process.

After calculating the expected signature value on the server side, it is necessary to compare the calculated signature with the one received. If the signatures match, it means that the request originated from our servers and can be trusted.

Event Update Webhook​

Request Body
{
    "person_type" : "natural_person",
    "account_type" : "natural_person_account",
    "person_id" : "22f5d028-0ce7-46f7-9b63-e7e38171b485",
    "account_id" : "e49ac344-f941-4668-9afb-a52ce4e5754a",
    "monitoring_topic" : "OFAC",
    "event" : "entered"
}

Below is the meaning of each field:

NameTypeDescription
person_typestringPerson type (natural_person or legal_person).
account_typestringAccount type (natural_person_account or legal_person_account).
person_idstringUnique identifier of the person, provided in the creation request.
account_idstringUnique identifier of the account, provided in the creation request.
monitoring_topicstringMonitoring topic in which the change occurred.
eventstringType of event that occurred, such as "entered" or "exited" for restrictive list topics.

The monitoring topic update request follows the format above and notifies a change in the status of one of the monitoring topics within the account. The HTTP method used is PUT, and the endpoint URL may also contain the event ID, depending on the client's needs. It is important to note that the request body is sent as UTF-8 encoded text.

Retries​

The notification is considered successfully delivered when an HTTP 200 status is returned. If delivery fails, up to 7 retry attempts will be made with the following intervals, until a 200 response is received or all attempts are exhausted:

  • 10 seconds
  • 40 seconds
  • 160 seconds
  • 640 seconds
  • 2560 seconds
  • 10240 seconds
  • 40960 seconds