Bloobank API Documentation

Every webhook delivery is signed. Verify the signature before parsing or acting on the payload — an unverified webhook is an injection vector for fake payment confirmations. The scheme is Webhook Signature v1: HMAC-SHA512 with your per-merchant shared secret. The secret is symmetric — Bloobank uses it to sign, you use it to verify. Treat it with the same care as a private key: anyone holding it can forge webhooks that pass your validation.

The signature header

X-Webhook-Signature: t=<timestamp>,v1=<signature>

Field	Value	Rules
`t`	Unix epoch in milliseconds (UTC), decimal integer (13 digits for 2026)	The instant Bloobank signed this attempt. Every retry is re-signed with a fresh `t`.
`v1`	HMAC-SHA512 signature, lowercase hex, 128 characters (64 bytes)	Computed over the signed string below.

The two fields are joined by a single comma, with no spaces, in the order shown. Parse tolerantly (split on ,, then on the first =), but this is the exact form emitted today.

What the signature covers — and what it does not

The signature covers the timestamp and the raw request body, nothing else:

The URL, query string, HTTP method, and all other headers are not signed.
Integrity and confidentiality of the transport are TLS’s job; the signature proves origin (only a holder of the secret can produce it) and freshness (the timestamp is bound into the signed bytes — a captured payload cannot be re-delivered later under a new timestamp without invalidating v1).

Verification — the procedure

Perform these steps before parsing or acting on the payload. Reject the delivery (any non-2xx response, e.g. 401) if any step fails.

Capture the raw request body bytes

Exactly as received — before any framework body-parser, JSON deserialization, or re-encoding touches them.

Parse the header

Split X-Webhook-Signature into t and v1.

Build the signed string

Concatenate, in order: the value of t, one ASCII dot . (0x2E), and the raw body bytes:

{t}.{rawBody}

Compute the expected signature

HMAC-SHA512 with key = your webhook secret (its UTF-8 bytes, used verbatim — do not hex- or base64-decode it) and message = the signed string. Encode the 64-byte result as lowercase hex.

Compare in constant time

Use your platform’s timing-safe comparison (crypto.timingSafeEqual, hmac.compare_digest, hmac.Equal, MessageDigest.isEqual, hash_equals, CryptographicOperations.FixedTimeEquals, …) against v1. Never use plain string equality.

Check freshness (strongly recommended)

Reject the delivery if |now − t| exceeds your tolerance — 5 minutes is a good default. Bloobank does not mandate this check, but it bounds the replay window. It is safe to enforce: every redelivery attempt carries a fresh t and a fresh v1, so rejecting a stale delivery never strands an order — the retry arrives with a valid recent signature.

Only after all checks pass should you parse the JSON body.

The three most common mistakes:

Verify the raw bytes — never a re-serialized version. If your framework parses the JSON and you re-stringify it to verify, key order, whitespace, escape sequences, or unicode normalization can differ by a single byte and the HMAC will not match. Capture the bytes as they arrived on the socket.
The delimiter is a dot . — not a colon. If you also integrate with the Bloobank IAM request-signing protocol (colon-separated canonical string), do not reuse that separator here. The webhook signed string has exactly one delimiter: {t}.{body}.
Use t from the header — not your own clock. The timestamp inside the signed string must be the exact t value Bloobank sent. Reading your own clock produces a different string and a guaranteed mismatch.

End-to-end worked example

Every value below — including the signature — is real and reproducible. Because the scheme is a symmetric HMAC, you can recompute v1 yourself from the secret, the timestamp, and the body, and use this example as an integration test fixture. Inputs:

Field	Value
Webhook secret	`9fT2xKq8LmWv4RnZbYcP6hAzE3gUsN7dJ5eB1oCiHtQu`
`t`	`1785931205231` (= `2026-08-05T12:00:05.231Z`)
Raw body	the exact 826-byte single-line JSON below

Raw body (exact bytes, no line breaks):

{"id":"ord_68f1a2b3c4d5e6f7a8b9c0d1","kind":"Payment.Order","wallet":"mrc-acme-main-7f3a","ordVersion":3,"direction":"IN","status":"SUCCESS","network":"br.gov.bcb.pix","idempotencyKey":"3e1b74a0-5c2d-4f6e-9a8b-1c0d2e3f4a5b","amount":125000,"currency":"BRL","instrument":{"type":"PIX_CASH_IN_EMV_DYNAMIC","endToEndId":"E32074986202608051159a1b2c3d4e5f","expiresIn":3600,"debtorName":"Maria Oliveira","debtorDocument":"***.456.789-**","debtorAccount":null,"qrcode":null,"copypaste":null,"expiresAt":"2026-08-05T12:59:12.000Z"},"metadata":{"orderRef":"acme-9001"},"errorCode":null,"errorMessage":null,"createdAt":"2026-08-05T11:59:12.481Z","updatedAt":"2026-08-05T12:00:03.117Z","processedAt":"2026-08-05T12:00:03.117Z","selfName":"wallets/mrc-acme-main-7f3a/paymentOrders/ord_68f1a2b3c4d5e6f7a8b9c0d1","etag":"c8b1f0a9d2e37c46"}

Signed string — the timestamp, a dot, then the raw body:

1785931205231.{"id":"ord_68f1a2b3c4d5e6f7a8b9c0d1","kind":"Payment.Order",…

Expected signature — HMAC-SHA512(key = secret, message = signed string), lowercase hex:

649e630dde051d6ad1610794c61667fad78a3b28b860e29f3d191c7b49fcfb7a5ff5c48758ec7c2b36c609864da4e0066fb407e086f0b3bfeaa93b6615767af4

The HTTP request you receive:

POST /webhooks/bloobank/cash-in HTTP/1.1
Host: api.merchant.example
Content-Type: application/json
User-Agent: HttpClient
X-Webhook-Signature: t=1785931205231,v1=649e630dde051d6ad1610794c61667fad78a3b28b860e29f3d191c7b49fcfb7a5ff5c48758ec7c2b36c609864da4e0066fb407e086f0b3bfeaa93b6615767af4
Content-Length: 826

{"id":"ord_68f1a2b3c4d5e6f7a8b9c0d1","kind":"Payment.Order",…}

Your validation, step by step:

Raw body captured: 826 bytes.
Header parsed: t = 1785931205231, v1 = 649e63…67af4.
Signed string built: 1785931205231. + raw body.
HMAC-SHA512 with the secret → matches v1. ✅
Freshness: |now − 1785931205231| within tolerance. ✅
Parse JSON, persist, then acknowledge 200 text/plain success.

Minimal test vector (for unit tests)

A tiny fixture with no domain payload, convenient for a signature unit test:

Field	Value
Secret	`test-secret`
`t`	`1700000000000`
Raw body	`{"ping":"pong"}`
Signed string	`1700000000000.{"ping":"pong"}`
Expected `v1`	`af2a6813f3befcb72870a77700748a4820145f0b736aa8fbc6282bf8c5f00036f5ac3684a714f8c38d8aa7e0912a8cd3bbb977b6ed38ffefee8518101353cf14`

If your implementation reproduces this v1, your canonical construction, key handling, and hex encoding are all correct.

Reference implementations

Illustrative, minimal, and complete. Any mainstream HTTP framework works — the only hard requirement is access to the raw body bytes. Each verifier parses t/v1, enforces the 5-minute freshness window, computes HMAC-SHA512 over {t}.{rawBody}, compares in constant time, and acknowledges with 200 text/plain success only after durable persistence.

All six implementations reproduce the test vector above. Wire it into your unit tests before pointing Bloobank at the endpoint.

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const TOLERANCE_MS = 5 * 60_000

export function verifyWebhookSignature(
  header: string | undefined,
  rawBody: Buffer,
  secret: string,
): boolean {
  if (!header) return false

  const fields = new Map(header.split(',').map((part) => {
    const eq = part.indexOf('=')
    return [part.slice(0, eq), part.slice(eq + 1)] as const
  }))
  const t = fields.get('t')
  const v1 = fields.get('v1')
  if (!t || !v1) return false

  if (Math.abs(Date.now() - Number(t)) > TOLERANCE_MS) return false

  // Chained updates hash the exact concatenation {t}.{rawBody} with no
  // intermediate string decode of the body bytes.
  const expected = createHmac('sha512', secret)
    .update(t).update('.').update(rawBody)
    .digest()
  const received = Buffer.from(v1, 'hex')

  // Length guard: timingSafeEqual throws on length mismatch, and it also
  // catches malformed hex (Buffer.from stops at the first invalid byte).
  return received.length === expected.length && timingSafeEqual(expected, received)
}

const app = express()
const secret = process.env.BLOOBANK_WEBHOOK_SECRET!   // from your secret manager

function bloobankWebhookHandler(persist: (order: unknown) => Promise<void>) {
  return async (req: express.Request, res: express.Response) => {
    if (!verifyWebhookSignature(req.header('X-Webhook-Signature'), req.body, secret))
      return res.status(401).type('text/plain').send('invalid signature')

    const order = JSON.parse((req.body as Buffer).toString('utf8'))
    await persist(order)                              // durable BEFORE acknowledging
    return res.status(200).type('text/plain').send('success')
  }
}

// express.raw keeps the exact bytes. Never mount express.json() on these routes.
app.post('/webhooks/bloobank/cash-in', express.raw({ type: 'application/json' }), bloobankWebhookHandler(persistCashIn))
app.post('/webhooks/bloobank/cash-out', express.raw({ type: 'application/json' }), bloobankWebhookHandler(persistCashOut))

import hashlib
import hmac
import json
import time

from flask import Flask, Response, request

app = Flask(__name__)
SECRET = b"..."                      # from your secret manager, UTF-8 bytes
TOLERANCE_MS = 5 * 60 * 1000


def verify_webhook_signature(header: str | None, raw_body: bytes) -> bool:
    if not header:
        return False
    fields = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = fields.get("t"), fields.get("v1")
    if not t or not v1:
        return False
    if abs(time.time() * 1000 - int(t)) > TOLERANCE_MS:
        return False
    signed = t.encode("ascii") + b"." + raw_body
    expected = hmac.new(SECRET, signed, hashlib.sha512).hexdigest()
    return hmac.compare_digest(expected, v1.lower())


@app.post("/webhooks/bloobank/cash-in")
def cash_in():
    raw = request.get_data()          # raw bytes, before any parsing
    if not verify_webhook_signature(request.headers.get("X-Webhook-Signature"), raw):
        return Response("invalid signature", status=401, mimetype="text/plain")
    order = json.loads(raw)
    persist(order)                    # durable BEFORE acknowledging
    return Response("success", mimetype="text/plain")

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/hex"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const toleranceMs int64 = 5 * 60 * 1000

func verifyWebhookSignature(header string, rawBody []byte, secret string) bool {
	if header == "" {
		return false
	}
	fields := map[string]string{}
	for _, part := range strings.Split(header, ",") {
		if k, v, ok := strings.Cut(part, "="); ok {
			fields[k] = v
		}
	}
	t, v1 := fields["t"], fields["v1"]
	if t == "" || v1 == "" {
		return false
	}

	tMs, err := strconv.ParseInt(t, 10, 64)
	if err != nil {
		return false
	}
	if diff := time.Now().UnixMilli() - tMs; diff > toleranceMs || diff < -toleranceMs {
		return false
	}

	// Key = the secret's UTF-8 bytes, verbatim; message = {t}.{rawBody}
	mac := hmac.New(sha512.New, []byte(secret))
	mac.Write([]byte(t))
	mac.Write([]byte("."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)

	received, err := hex.DecodeString(strings.ToLower(v1))
	if err != nil {
		return false
	}
	return hmac.Equal(expected, received) // constant-time
}

func bloobankWebhookHandler(persist func(rawBody []byte) error) http.HandlerFunc {
	secret := os.Getenv("BLOOBANK_WEBHOOK_SECRET") // from your secret manager
	return func(w http.ResponseWriter, r *http.Request) {
		rawBody, err := io.ReadAll(r.Body) // raw bytes, before any decoding
		if err != nil {
			http.Error(w, "read error", http.StatusInternalServerError)
			return
		}
		if !verifyWebhookSignature(r.Header.Get("X-Webhook-Signature"), rawBody, secret) {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}
		if err := persist(rawBody); err != nil { // durable BEFORE acknowledging
			http.Error(w, "persistence failed", http.StatusInternalServerError)
			return
		}
		w.Header().Set("Content-Type", "text/plain")
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("success"))
	}
}

func main() {
	http.HandleFunc("/webhooks/bloobank/cash-in", bloobankWebhookHandler(persistCashIn))
	http.HandleFunc("/webhooks/bloobank/cash-out", bloobankWebhookHandler(persistCashOut))
	http.ListenAndServe(":8080", nil)
}

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.Map;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BloobankWebhookController {

    private static final long TOLERANCE_MS = 5 * 60 * 1000L;

    // From your secret manager. UTF-8 bytes, verbatim — never hex/base64-decode.
    private final byte[] secret =
        System.getenv("BLOOBANK_WEBHOOK_SECRET").getBytes(StandardCharsets.UTF_8);

    static boolean verifyWebhookSignature(String header, byte[] rawBody, byte[] secret) {
        if (header == null) return false;

        Map<String, String> fields = new HashMap<>();
        for (String part : header.split(",")) {
            int eq = part.indexOf('=');
            if (eq > 0) fields.put(part.substring(0, eq), part.substring(eq + 1));
        }
        String t = fields.get("t");
        String v1 = fields.get("v1");
        if (t == null || v1 == null) return false;

        long tMs;
        try { tMs = Long.parseLong(t); } catch (NumberFormatException e) { return false; }
        if (Math.abs(System.currentTimeMillis() - tMs) > TOLERANCE_MS) return false;

        byte[] expected;
        try {
            Mac mac = Mac.getInstance("HmacSHA512");
            mac.init(new SecretKeySpec(secret, "HmacSHA512"));
            mac.update(t.getBytes(StandardCharsets.US_ASCII));
            mac.update((byte) '.');
            expected = mac.doFinal(rawBody);          // {t}.{rawBody}
        } catch (Exception e) {
            return false;
        }

        byte[] received;
        try { received = HexFormat.of().parseHex(v1.toLowerCase()); }
        catch (IllegalArgumentException e) { return false; }

        return MessageDigest.isEqual(expected, received); // constant-time
    }

    // byte[] binding hands you the raw request bytes — no JSON deserialization first.
    @PostMapping(path = "/webhooks/bloobank/cash-in", consumes = "application/json")
    public ResponseEntity<String> cashIn(
            @RequestHeader(value = "X-Webhook-Signature", required = false) String signature,
            @RequestBody byte[] rawBody) {
        if (!verifyWebhookSignature(signature, rawBody, secret)) {
            return ResponseEntity.status(401)
                .contentType(MediaType.TEXT_PLAIN).body("invalid signature");
        }
        persist(rawBody);                             // durable BEFORE acknowledging
        return ResponseEntity.ok()
            .contentType(MediaType.TEXT_PLAIN).body("success");
    }
}

<?php

const TOLERANCE_MS = 5 * 60 * 1000;

function verifyWebhookSignature(?string $header, string $rawBody, string $secret): bool
{
    if ($header === null || $header === '') {
        return false;
    }

    $fields = [];
    foreach (explode(',', $header) as $part) {
        $eq = strpos($part, '=');
        if ($eq !== false) {
            $fields[substr($part, 0, $eq)] = substr($part, $eq + 1);
        }
    }
    $t  = $fields['t']  ?? null;
    $v1 = $fields['v1'] ?? null;
    if ($t === null || $v1 === null) {
        return false;
    }

    if (abs((int) round(microtime(true) * 1000) - (int) $t) > TOLERANCE_MS) {
        return false;
    }

    // Key = the secret string verbatim; message = {t}.{rawBody}
    $expected = hash_hmac('sha512', $t . '.' . $rawBody, $secret);

    return hash_equals($expected, strtolower($v1)); // constant-time
}

$rawBody = file_get_contents('php://input');          // raw bytes, before any parsing
$header  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? null;
$secret  = getenv('BLOOBANK_WEBHOOK_SECRET');         // from your secret manager

if (!verifyWebhookSignature($header, $rawBody, $secret)) {
    http_response_code(401);
    header('Content-Type: text/plain');
    echo 'invalid signature';
    exit;
}

$order = json_decode($rawBody, true);
persist($order);                                      // durable BEFORE acknowledging

http_response_code(200);
header('Content-Type: text/plain');
echo 'success';

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

const long ToleranceMs = 5 * 60 * 1000;

static bool VerifyWebhookSignature(string? header, byte[] rawBody, string secret)
{
    if (string.IsNullOrEmpty(header)) return false;

    var fields = new Dictionary<string, string>();
    foreach (var part in header.Split(','))
    {
        var eq = part.IndexOf('=');
        if (eq > 0) fields[part[..eq]] = part[(eq + 1)..];
    }
    if (!fields.TryGetValue("t", out var t) || !fields.TryGetValue("v1", out var v1))
        return false;

    if (!long.TryParse(t, out var tMs)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - tMs) > ToleranceMs)
        return false;

    // Key = the secret's UTF-8 bytes, verbatim; message = {t}.{rawBody}
    var prefix = Encoding.ASCII.GetBytes(t + ".");
    var signed = new byte[prefix.Length + rawBody.Length];
    prefix.CopyTo(signed, 0);
    rawBody.CopyTo(signed, prefix.Length);

    using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secret));
    var expected = hmac.ComputeHash(signed);

    byte[] received;
    try { received = Convert.FromHexString(v1); }
    catch (FormatException) { return false; }

    return CryptographicOperations.FixedTimeEquals(expected, received); // constant-time
}

var app = WebApplication.CreateBuilder(args).Build();
var secret = Environment.GetEnvironmentVariable("BLOOBANK_WEBHOOK_SECRET")!;

app.MapPost("/webhooks/bloobank/cash-in", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);           // raw bytes, before any model binding
    var rawBody = buffer.ToArray();

    var header = request.Headers["X-Webhook-Signature"].ToString();
    if (!VerifyWebhookSignature(header, rawBody, secret))
        return Results.Text("invalid signature", "text/plain", statusCode: 401);

    var order = JsonSerializer.Deserialize<JsonElement>(rawBody);
    await Persist(order);                             // durable BEFORE acknowledging
    return Results.Text("success", "text/plain", statusCode: 200);
});

app.Run();

Troubleshooting signature mismatches

Work through this list in order — the first three items cover the overwhelming majority of failed verifications.

Re-serialized body. Your framework parsed the JSON and you verified against JSON.stringify(parsed) instead of the raw bytes. Key order, whitespace, or unicode escapes differ → different bytes → different HMAC. Verify the bytes as received.
Body parser consumed the raw bytes. In Express, a global express.json() replaces the raw body before your handler runs. Mount express.raw() on the webhook routes (or capture the buffer with express.json({ verify })). Equivalent pitfalls exist in every framework.
Wrong algorithm. The scheme is HMAC-SHA512 — the signature is 128 hex characters. If you computed 64 hex characters, you used a 256-bit hash; switch to SHA-512.
Wrong delimiter. The signed string is {t}.{body} with a single dot. A colon (the IAM request-signing separator), a comma, or nothing at all will not match.
Signed the body only. The timestamp is part of the signed string. HMAC(body) alone never matches.
Used your own clock for t. The signed string must embed the exact t from the header, not a timestamp you generated.
Decoded the secret. The secret’s UTF-8 bytes are the HMAC key, verbatim. Do not hex-decode or base64-decode it first.
Wrong output encoding. v1 is hex, not base64. Compare byte-to-byte (decode the hex) or lowercase-hex to lowercase-hex — always with a constant-time comparison.
Uppercase hex. If your HMAC helper emits uppercase hex, normalize before comparing; Bloobank emits lowercase.
Middleware rewrote the body. An API gateway, WAF, or framework “sanitizer” that re-encodes, pretty-prints, or normalizes the JSON changes the bytes in flight. The signature must be verified against exactly what Bloobank sent — disable body transformations on the webhook path.

If verification passes but deliveries still show as failed on the Bloobank side, the problem is the acknowledgement, not the signature — re-read the success contract. A JSON-quoted "success", an empty body, or the token ok are the usual suspects.

Retry & delivery

What happens when verification or acknowledgement fails.

Webhook payload

The canonical PaymentOrder document.

Best practices

Idempotency, ordering, secret handling.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

Verifying signatures

The signature header

What the signature covers — and what it does not

Verification — the procedure

End-to-end worked example

Minimal test vector (for unit tests)

Reference implementations

Troubleshooting signature mismatches

Next

Retry & delivery

Webhook payload

Best practices

​The signature header

​What the signature covers — and what it does not

​Verification — the procedure

​End-to-end worked example

​Minimal test vector (for unit tests)

​Reference implementations

​Troubleshooting signature mismatches

​Next

Retry & delivery

Webhook payload

Best practices

The signature header

What the signature covers — and what it does not

Verification — the procedure

End-to-end worked example

Minimal test vector (for unit tests)

Reference implementations

Troubleshooting signature mismatches

Next