Skip to main content

Webhook

Fraud status updates (for registrations that are routed to manual review or responded with a Pending status) are notified via Webhook. To enable this, you must configure an endpoint URL and a secret_token used to sign the request through our support team.

Although not recommended, clients may alternatively use the polling technique. In this case, simply avoid configuring a webhook endpoint and rely on the registration retrieval endpoints to perform 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 Signature header, similar to the authentication process.

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

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 change in fraud status. It is important to note that the request uses the HTTP POST verb and the body is sent as UTF-8 encoded string.

Retries​

A notification is considered successful when it receives an HTTP 200 status code in response. If the notifications fail, the system will attempt up to 5 retries at the following intervals, until a 200 is returned or all attempts are exhausted:

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