Skip to main content

Webhook

Updates in fraud status (for events that are forwarded for manual analysis or responded to as Pending) are notified via Webhook. To do so, it is necessary, through the support team, to configure an endpoint address where we will notify updates, as well as a signature_key that will be used to sign the request.

The client may also use the polling technique. In this case, simply do not configure the webhook endpoint and use the retrieval endpoints to proceed with polling.

Attention

For security reasons, all Webhook requests will only be performed on endpoints served via 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, similar to the authentication process.

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

Event Update Webhook​

Request Body
    {
        "id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

The event analysis status update request has the format above and notifies of changes in fraud status. The method used is PUT, and the endpoint address may also contain the event ID, according to the client's needs. It is important to highlight that the request body is sent as UTF-8 encoded text.

Examples of event update endpoints:

The {event} field, located in the request URL, can assume the following values, depending on the event being notified:

  • bill_payment
  • bankslip
  • wire_transfer
  • withdrawal
  • pix

The event_date field indicates the date and time the notification was created and may be in the past if previous notification attempts failed.

Retries​

The notification is considered completed when it receives an HTTP Status 200 response. If notifications fail, 7 retries will be made, with the following intervals, until a 200 is returned or the attempts are exhausted:

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