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.

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 — POST for these notifications.
payload	The request body exactly as received, byte for byte.
signature_key	The secret you agreed on with support (also called secret_token). 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.get_data(), file_get_contents('php://input'), express.raw() and so on.

Accented characters in the payload

The body is serialized with ensure_ascii=False, meaning accented characters are sent as literal UTF-8 ("João") rather than escaped. 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 a field contains an accent.

Validation examples

Python

import hashlib
import hmac

SIGNATURE_KEY = "YOUR_SECRET_TOKEN"
WEBHOOK_URL = "https://seu-dominio.com/webhooks/qitech"
HTTP_METHOD = "HTTP_VERB"  # see the table above


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, HTTP_METHOD, raw_body)
    # compare_digest prevents timing attacks
    return hmac.compare_digest(expected, received_signature)


# Exemplo com Flask
from flask import Flask, request

app = Flask(__name__)


@app.route("/webhooks/qitech", methods=[HTTP_METHOD])
def receive_webhook():
    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

    event = request.get_json()  # parse only after validating
    print(event)
    return "", 200

PHP

<?php

const SIGNATURE_KEY = 'YOUR_SECRET_TOKEN';
const WEBHOOK_URL   = 'https://seu-dominio.com/webhooks/qitech';
const HTTP_METHOD   = 'HTTP_VERB'; // see the table above

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

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

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

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

$event = json_decode($rawBody, true);                   // parse only after validating

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";
const HTTP_METHOD = "HTTP_VERB"; // see the table above

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

function isValid(receivedSignature, rawBody, url, method) {
  const expected = calculateSignature(url, method, 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.use(
  "/webhooks/qitech",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const received = req.get("Signature") || "";

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

    const event = JSON.parse(rawBody); // parse only after validating
    console.log(event);
    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";
    private static final String HTTP_METHOD = "HTTP_VERB"; // see the table above

    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,
                                  String url, String method) throws Exception {
        String expected = calculateSignature(url, method, 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:

@RestController
public class WebhookController {

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

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

        // parse only after validating (ex.: com 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";
    public const string WebhookUrl = "https://seu-dominio.com/webhooks/qitech";
    public const string HttpMethod = "HTTP_VERB"; // see the table above

    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,
                               string url, string method)
    {
        var expected = CalculateSignature(url, method, 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.MapMethods("/webhooks/qitech", new[] { WebhookSignature.HttpMethod }, 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,
            WebhookSignature.WebhookUrl, WebhookSignature.HttpMethod))
    {
        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 changes the signature. Use exactly the URL configured with support.
3. Is the method correct and uppercase? For these notifications it is 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.

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