Skip to main content

Webhook

Status updates (for registrations that are sent for manual analysis or returned as Pending) are notified via Webhook. To enable this, you must configure an endpoint URL through the support team, where we will send update notifications, as well as a secret_token used to sign the request.

Although not recommended, the client may alternatively use the polling technique. In this case, simply do not configure the webhook endpoint and use the record retrieval endpoints to proceed with polling.

Signature​

Example of signature calculation in Python

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

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

After calculating the expected signature value on your server, you must compare the calculated signature with the one sent. If the signatures match, it means the request came from our servers and is trustworthy.

Request​

curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"natural_person_id": "538509",  "analysis_status": "manually_approved", "event_date": "2024-11-13T17:52:50Z", "reason": "manually_approved"}'

The request follows the format above and notifies the status change. It is important to note that the request uses the HTTP POST method and the request body is sent as UTF-8 encoded string.

Retry Attempts​

A notification is considered successfully delivered when it receives an HTTP Status 200 as a response. If the notification fails, 5 retry attempts will be made with the following intervals, until a 200 is returned or all attempts are exhausted:

  • 30 seconds
  • 60 seconds
  • 120 seconds
  • 240 seconds
  • 360 seconds