Cardholder Alerts

The alerts generated by the antifraud tool are notified through Webhook. To enable that, you need to work with our support team to configure an endpoint address where we will send the notifications, as well as a secret_token that will be used to sign the request.

In this notification we send information about the alerts generated, along with which cardholder they refer to, so that the client can take some action — for example, sending a push notification to the cardholder.

Request

Request Body

    {
        "alert_key": "123456",
        "cardholder_id": "ef47bc3f-61ac-4b85-ad67-0cfa3a422201",
        "company_name": "Cliente 1",
        "irregularity_type" : "fraud",
        "risk_level": "critical"
    }

The request has the format above and notifies the opening of a new alert for a cardholder — described by the cardholder_id.

Webhook signature

To guarantee that the request received at your endpoint came from our servers, we send an HMAC signature in the Signature header. You recompute that signature on your side and compare it with the one received — if they match, the request is trustworthy.

How the signature is computed

Signature = HMAC-SHA1(signature_key, endpoint + method + payload)  →  hexadecimal

The three components are concatenated in this order, with no separator:

Component	What it is
endpoint	The full URL of your webhook, exactly as configured with support (including https:// and any query string).
method	The HTTP verb in uppercase — always POST for alert notifications.
payload	The request body exactly as received, byte for byte.
signature_key	The secret_token you agreed on with support. It is the HMAC key, not part of the message.

Use the raw body, never re-serialized JSON

The signature is computed over the exact bytes of the body. If you deserialize the JSON and serialize it again before validating, key order and whitespace change, and the signature will never match.

Read the body as a raw string/bytes first, validate the signature, and only then parse it. In the examples below this appears as request.data, file_get_contents('php://input'), req.rawBody and so on.

Accented characters in the payload

We serialize the body with ensure_ascii=False, meaning accented characters are sent as literal UTF-8 ("João") rather than escaped ("João"). Treat the body as UTF-8 when computing the HMAC — this is the default in every language below, but it is the most common cause of a mismatched signature when company_name contains an accent.

Validation examples

Python

import hashlib
import hmac

SIGNATURE_KEY = "YOUR_SECRET_TOKEN"
WEBHOOK_URL = "https://seu-dominio.com/webhooks/qitech/alertas"


def calculate_signature(endpoint: str, method: str, payload: str) -> str:
    hmac_obj = hmac.new(
        SIGNATURE_KEY.encode("utf-8"),
        (endpoint + method + payload).encode("utf-8"),
        hashlib.sha1,
    )
    return hmac_obj.hexdigest()


def is_valid(received_signature: str, raw_body: str) -> bool:
    expected = calculate_signature(WEBHOOK_URL, "POST", raw_body)
    # compare_digest prevents timing attacks
    return hmac.compare_digest(expected, received_signature)


# Example with Flask
from flask import Flask, request

app = Flask(__name__)


@app.route("/webhooks/qitech/alertas", methods=["POST"])
def receive_alert():
    raw_body = request.get_data(as_text=True)  # raw body, no parsing
    received = request.headers.get("Signature", "")

    if not is_valid(received, raw_body):
        return "", 401

    alert = request.get_json()  # parse only after validating
    print(alert["cardholder_id"], alert["risk_level"])
    return "", 200

PHP

<?php

const SIGNATURE_KEY = 'YOUR_SECRET_TOKEN';
const WEBHOOK_URL   = 'https://seu-dominio.com/webhooks/qitech/alertas';

function calculateSignature(string $endpoint, string $method, string $payload): string
{
    return hash_hmac('sha1', $endpoint . $method . $payload, SIGNATURE_KEY);
}

function isValid(string $receivedSignature, string $rawBody): bool
{
    $expected = calculateSignature(WEBHOOK_URL, 'POST', $rawBody);
    // hash_equals prevents timing attacks
    return hash_equals($expected, $receivedSignature);
}

// Receiving the notification
$rawBody  = file_get_contents('php://input');           // raw body, no parsing
$received = $_SERVER['HTTP_SIGNATURE'] ?? '';

if (!isValid($received, $rawBody)) {
    http_response_code(401);
    exit;
}

$alert = json_decode($rawBody, true);                   // parse only after validating
error_log($alert['cardholder_id'] . ' - ' . $alert['risk_level']);

http_response_code(200);

Node.js

const crypto = require("crypto");
const express = require("express");

const SIGNATURE_KEY = "YOUR_SECRET_TOKEN";
const WEBHOOK_URL = "https://seu-dominio.com/webhooks/qitech/alertas";

function calculateSignature(endpoint, method, payload) {
  return crypto
    .createHmac("sha1", SIGNATURE_KEY)
    .update(endpoint + method + payload, "utf8")
    .digest("hex");
}

function isValid(receivedSignature, rawBody) {
  const expected = calculateSignature(WEBHOOK_URL, "POST", rawBody);
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(receivedSignature, "utf8");
  // timingSafeEqual requires equal-length buffers
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// express.raw preserves the raw body — do NOT use express.json() on this route
app.post(
  "/webhooks/qitech/alertas",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const received = req.get("Signature") || "";

    if (!isValid(received, rawBody)) {
      return res.sendStatus(401);
    }

    const alert = JSON.parse(rawBody); // parse only after validating
    console.log(alert.cardholder_id, alert.risk_level);
    res.sendStatus(200);
  },
);

app.listen(3000);

Java

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class WebhookSignature {

    private static final String SIGNATURE_KEY = "YOUR_SECRET_TOKEN";
    private static final String WEBHOOK_URL =
            "https://seu-dominio.com/webhooks/qitech/alertas";

    public static String calculateSignature(String endpoint, String method, String payload)
            throws Exception {
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(
                SIGNATURE_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA1"));

        byte[] digest = mac.doFinal(
                (endpoint + method + payload).getBytes(StandardCharsets.UTF_8));

        StringBuilder hex = new StringBuilder(digest.length * 2);
        for (byte b : digest) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }

    public static boolean isValid(String receivedSignature, String rawBody)
            throws Exception {
        String expected = calculateSignature(WEBHOOK_URL, "POST", rawBody);
        // MessageDigest.isEqual prevents timing attacks
        return MessageDigest.isEqual(
                expected.getBytes(StandardCharsets.UTF_8),
                receivedSignature.getBytes(StandardCharsets.UTF_8));
    }
}

In Spring Boot, receive the body as a String to preserve the original bytes:

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class AlertController {

    @PostMapping("/webhooks/qitech/alertas")
    public ResponseEntity<Void> receiveAlert(
            @RequestBody String rawBody,                       // raw body, no parsing
            @RequestHeader(value = "Signature", required = false) String signature)
            throws Exception {

        if (signature == null || !WebhookSignature.isValid(signature, rawBody)) {
            return ResponseEntity.status(401).build();
        }

        // parse only after validating (e.g. with Jackson)
        return ResponseEntity.ok().build();
    }
}

C#

using System;
using System.Security.Cryptography;
using System.Text;

public static class WebhookSignature
{
    private const string SignatureKey = "YOUR_SECRET_TOKEN";
    private const string WebhookUrl =
        "https://seu-dominio.com/webhooks/qitech/alertas";

    public static string CalculateSignature(string endpoint, string method, string payload)
    {
        using var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(SignatureKey));
        var digest = hmac.ComputeHash(Encoding.UTF8.GetBytes(endpoint + method + payload));
        return Convert.ToHexString(digest).ToLowerInvariant();
    }

    public static bool IsValid(string receivedSignature, string rawBody)
    {
        var expected = CalculateSignature(WebhookUrl, "POST", rawBody);
        // FixedTimeEquals prevents timing attacks
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(receivedSignature));
    }
}

In ASP.NET Core, read the raw body before any deserialization:

app.MapPost("/webhooks/qitech/alertas", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body, Encoding.UTF8);
    var rawBody = await reader.ReadToEndAsync();          // raw body, no parsing

    var received = request.Headers["Signature"].ToString();

    if (!WebhookSignature.IsValid(received, rawBody))
    {
        return Results.Unauthorized();
    }

    // parse only after validating
    return Results.Ok();
});

Signature not matching? Check in this order

1. Was the body re-serialized? This is the most frequent cause. Use the raw body.
2. Is the URL identical? A trailing slash added or removed (/alertas vs /alertas/) changes the signature. Use exactly the URL configured with support.
3. Is the method uppercase? It must be POST, not post.
4. Is the concatenation order right? It is endpoint + method + payload, in that order.
5. Is the digest lowercase hexadecimal? It is not Base64.

Retries

A notification is considered delivered when it receives an HTTP Status 200 in response. If the notifications fail, 5 retries will be made, at the following intervals, until a 200 is returned or the attempts run out:

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