Webhooks

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "Banking.Deposit.StatusUpdated",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "id": "a12f5e4d-3c6e-4b2a-9f4d-8e2b1c3d4e5f",
    "userId": "c56e7f8a-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "asset": "EUR",
    "amount": 1000.0
  }
}

{
  "id": "a12f5e4d-3c6e-4b2a-9f4d-8e2b1c3d4e5f",
  "userId": "c56e7f8a-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "type": "DEPOSIT",
  "status": "SUCCESS",
  "description": "Deposit from bank transfer",
  "asset": "EUR",
  "amount": 1000.0,
  "debtor": {
    "refAddressId": "ref-123",
    "bankName": "ABC Bank",
    "bankAddressCountry": "IT",
    "accountHolderName": "John Smith",
    "country": "IT",
    "accountNumber": "",
    "routingCodes": {},
    "iban": "IT123A456B789C012D345E678F90",
    "bic": "AABCDEFFXXX",
    "address": {
      "line1": "Via Roma 1",
      "city": "Roma",
      "postalCode": "00100",
      "country": "IT"
    }
  },
  "creditor": {
    "refAddressId": "ref-456",
    "bankName": "ACME Bank",
    "bankAddressCountry": "DE",
    "accountHolderName": "Acme Corporation",
    "country": "DE",
    "accountNumber": "",
    "routingCodes": {},
    "iban": "DE123A456B789C012D345E678F90",
    "bic": "AABCDEFFXXX",
    "address": {
      "line1": "Friedrichstr. 100",
      "city": "Berlin",
      "postalCode": "10117",
      "country": "DE"
    }
  },
  "source": "FiatRepublic",
  "sourceRefId": "fr_txn_123456",
  "createdTimestamp": "2025-01-15T12:00:00.000Z",
  "approvedTimestamp": "2025-01-15T12:30:00.000Z",
  "processedTimestamp": "2025-01-15T12:56:36.000Z"
}

{
  "id": "987e6543-e21b-12d3-a456-426614174000",
  "userId": "987e6543-e21b-12d3-a456-426614174999",
  "description": "Monthly payment",
  "destination": "IT60X0542811101000000123456",
  "destinationParams": { "bic": "AABCDEFX" },
  "network": "SEPA",
  "amount": 500.0,
  "fee": 1.5,
  "asset": "EUR",
  "status": "SUCCESS",
  "isInstant": false,
  "timestamp": "2025-01-15T12:00:00.000Z"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "userId": "987e6543-e21b-12d3-a456-426614174999",
  "clientId": "qwertyuiop-1234-5678-9012-abcdefabcdef",
  "description": "Monthly subscription payment",
  "debtor": {
    "internalAddressId": "internal-123",
    "asset": "EUR",
    "address": "DE89370400440532013000",
    "addressParams": {},
    "network": "SEPA",
    "amount": 100.0,
    "fee": 1.5
  },
  "creditor": {
    "payeeAddressId": "payee-321",
    "asset": "EUR",
    "address": "IT60X0542811101000000123456",
    "addressParams": { "bic": "AABCDEFX" },
    "network": "SEPA",
    "amount": 100.0
  },
  "exchangeInfo": {
    "rate": 1.0
  },
  "status": "SUCCESS",
  "isInstant": false,
  "createdTimestamp": "2025-01-15T10:00:00.000Z",
  "approvedTimestamp": "2025-01-15T10:05:00.000Z",
  "processedTimestamp": "2025-01-15T10:30:00.000Z"
}

{
  "id": "vac_abc123def456",
  "masterFiatAccountId": "fac_789xyz",
  "owner": {
    "id": "eus_owner123",
    "type": "END_USER"
  },
  "currency": "EUR",
  "bankDetails": {
    "bankName": "Example Bank",
    "accountHolderName": "Acme Corporation",
    "country": "DE",
    "bankAddressCountry": "DE",
    "accountNumber": "",
    "routingCodes": [{ "type": "sortcode", "value": "12-34-56" }],
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  },
  "businessId": "biz_xyz456",
  "label": "EUR Deposit Account",
  "status": "ACTIVE",
  "createdAt": "2025-01-15T12:00:00.000Z",
  "updatedAt": "2025-01-15T12:30:00.000Z",
  "userId": "user_123",
  "endUserId": "eus_owner123"
}

{
  "userId": "1a66db8f-4043-4035-91df-615b3a7ac073",
  "sequence": 123,
  "assets": [
    {
      "name": "EUR",
      "available": 1500.5,
      "allocated": 100.0
    },
    {
      "name": "USD",
      "available": 2000.0,
      "allocated": 0.0
    }
  ]
}

{
  "id": "eus_ong3zm73p8dr0b2jkr",
  "userId": "c56e7f8a-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "person": {
    "firstName": "Mario",
    "middleName": "",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com",
    "phone": "+393121212",
    "dob": "1990-01-01",
    "birthCountry": "IT",
    "nationality": ["IT"],
    "address": {
      "line1": "Via Roma 1022",
      "line2": "",
      "city": "Milano",
      "state": "MI",
      "postalCode": "20100",
      "country": "IT"
    }
  },
  "tags": [],
  "status": "ACTIVE",
  "riskRating": "LOW",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

{
  "id": "eus_abc123def456ghi789",
  "userId": "987e6543-e21b-12d3-a456-426614174999",
  "companyName": "Acme Corporation Ltd",
  "tradingName": "Acme Trading Co",
  "type": "LIMITED",
  "registrationNumber": "12345678",
  "registrationDate": "2020-01-01",
  "registeredAddress": {
    "line1": "123 Business Street",
    "line2": "Suite 100",
    "city": "London",
    "state": "England",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "tradingAddress": {
    "line1": "456 Trade Avenue",
    "line2": "",
    "city": "London",
    "state": "England",
    "postalCode": "EC1A 1BB",
    "country": "GB"
  },
  "businessPersons": [
    {
      "id": "bp_123",
      "businessEndUserId": "eus_abc123def456ghi789",
      "person": {
        "firstName": "John",
        "middleName": "",
        "lastName": "Smith",
        "email": "john.smith@acmecorp.com",
        "phone": "+442071234567",
        "dob": "1980-05-15",
        "birthCountry": "GB",
        "nationality": ["GB"],
        "address": {
          "line1": "123 Business Street",
          "line2": "Suite 100",
          "city": "London",
          "state": "England",
          "postalCode": "SW1A 1AA",
          "country": "GB"
        }
      },
      "personTypes": ["DIRECTOR", "UBO"],
      "ownership": "75.0",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "status": "ACTIVE",
  "riskRating": "LOW",
  "sector": "OTHER_PRODUCTS_SERVICES",
  "website": "https://acmecorp.com",
  "phone": "+442071234567",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

{
  "id": "payee-001",
  "userId": "user-123",
  "endUserId": "enduser-456",
  "type": "PERSON",
  "name": "John",
  "surname": "Doe",
  "company": "Company Inc.",
  "country": "IT",
  "state": "MI",
  "city": "Milano",
  "address": "Via Roma 123",
  "postalCode": "20100",
  "disabled": false,
  "deleted": false
}

{
  "id": "pa_123e4567",
  "payeeId": "payee-001",
  "name": "John Doe - EUR Account",
  "asset": "EUR",
  "address": "IT60X0542811101000000123456",
  "addressParams": { "bic": "AABCDEFX" },
  "network": "SEPA",
  "status": "CREATED",
  "comment": "Verified by compliance team",
  "confirmationStrategy": "API"
}

{
  "line1": "123 Main Street",
  "line2": "Apt 4B",
  "city": "Milano",
  "state": "MI",
  "postalCode": "20100",
  "country": "IT"
}

{
  "refAddressId": "ref_addr_123",
  "bankName": "Example Bank",
  "bankAddressCountry": "IT",
  "accountHolderName": "John Doe",
  "country": "IT",
  "accountNumber": "123456789",
  "routingCodes": { "sortcode": "12-34-56" },
  "iban": "IT60X0542811101000000123456",
  "bic": "AABCDEFX",
  "address": {
    "line1": "123 Main Street",
    "city": "Milano",
    "postalCode": "20100",
    "country": "IT"
  }
}

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

const app = express();

const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-----END PUBLIC KEY-----`;

const MAX_AGE_MINUTES = 5;

// Preserve raw body for signature verification
app.use(
  express.json({
    verify: (req, res, buf) => {
      req.rawBody = buf.toString('utf8');
    },
  }),
);

function verifyTimestamp(timestamp) {
  const ts = Number(timestamp);
  if (!Number.isFinite(ts)) return false;
  const requestTime = new Date(ts * 1000);
  const now = new Date();
  const diffMinutes = Math.abs((now - requestTime) / 60000);
  return diffMinutes <= MAX_AGE_MINUTES;
}

function verifySignature(rawBody, signatureBase64, timestamp) {
  try {
    const message = `${timestamp}.${rawBody}`;
    const digest = crypto.createHash('sha256').update(message, 'utf8').digest();

    const verifier = crypto.createVerify('RSA-SHA256');
    verifier.update(digest);
    verifier.end();

    return verifier.verify(PUBLIC_KEY_PEM, signatureBase64, 'base64');
  } catch (e) {
    console.error('Signature verification error:', e.message);
    return false;
  }
}

app.post('/webhooks/hercle', (req, res) => {
  const rawBody = req.rawBody || '';
  const payload = req.body;

  // Extract headers
  const signature = req.get('X-Webhook-Signature') || '';
  const timestamp = req.get('X-Webhook-Timestamp') || '';
  const webhookId = req.get('X-Webhook-Id') || '';

  // Verify timestamp (prevent replay attacks)
  if (!verifyTimestamp(timestamp)) {
    console.warn('Timestamp too old or invalid');
    return res.status(400).json({ error: 'Timestamp too old or invalid' });
  }

  // Verify signature
  if (!verifySignature(rawBody, signature, timestamp)) {
    console.warn('Invalid signature');
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Process the webhook
  console.log('Webhook verified:', {
    eventId: payload.eventId,
    eventType: payload.eventType,
    timestamp: payload.timestamp,
  });

  // Event data is already a parsed object
  const eventData = payload.data;

  // Handle the event based on type
  switch (payload.eventType) {
    case 'Banking.Deposit.StatusUpdated':
      handleDeposit(eventData);
      break;
    case 'VirtualAccount.Registered':
      handleVirtualAccount(eventData);
      break;
    case 'VirtualAccount.StatusUpdated':
      handleVirtualAccountStatus(eventData);
      break;
    // ... handle other event types
  }

  // Always return 200 to acknowledge receipt
  return res.status(200).json({ success: true });
});

app.listen(3000, () => {
  console.log('Webhook receiver listening on port 3000');
});

import hashlib
import time
from base64 import b64decode
from flask import Flask, request, jsonify
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

app = Flask(__name__)

PUBLIC_KEY_PEM = """-----BEGIN PUBLIC KEY-----
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-----END PUBLIC KEY-----"""

MAX_AGE_MINUTES = 5

def verify_timestamp(timestamp_str):
    try:
        ts = int(timestamp_str)
        request_time = ts
        now = int(time.time())
        diff_minutes = abs(now - request_time) / 60
        return diff_minutes <= MAX_AGE_MINUTES
    except (ValueError, TypeError):
        return False

def verify_signature(raw_body, signature_base64, timestamp):
    try:
        message = f"{timestamp}.{raw_body}"
        digest = hashlib.sha256(message.encode('utf-8')).digest()

        public_key = serialization.load_pem_public_key(PUBLIC_KEY_PEM.encode())
        signature = b64decode(signature_base64)

        public_key.verify(
            signature,
            digest,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception as e:
        print(f"Signature verification error: {e}")
        return False

@app.route('/webhooks/hercle', methods=['POST'])
def handle_webhook():
    raw_body = request.get_data(as_text=True)
    payload = request.get_json()

    # Extract headers
    signature = request.headers.get('X-Webhook-Signature', '')
    timestamp = request.headers.get('X-Webhook-Timestamp', '')
    webhook_id = request.headers.get('X-Webhook-Id', '')

    # Verify timestamp
    if not verify_timestamp(timestamp):
        return jsonify({'error': 'Timestamp too old or invalid'}), 400

    # Verify signature
    if not verify_signature(raw_body, signature, timestamp):
        return jsonify({'error': 'Invalid signature'}), 400

    # Process the webhook
    print(f"Webhook verified: {payload['eventType']}")

    # Always return 200 to acknowledge receipt
    return jsonify({'success': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

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

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Hercle exposes the public key as Base64-encoded DER (SubjectPublicKeyInfo).
// Paste it here as-is — the helper below wraps it as PEM. If your key already
// has -----BEGIN PUBLIC KEY----- headers, the helper will pass it through.
const string PublicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...";

const int MaxAgeMinutes = 5;

static string ToPem(string base64OrPem)
{
    if (base64OrPem.Contains("-----BEGIN")) return base64OrPem;
    var lines = new StringBuilder();
    for (var i = 0; i < base64OrPem.Length; i += 64)
        lines.AppendLine(base64OrPem.Substring(i, Math.Min(64, base64OrPem.Length - i)));
    return $"-----BEGIN PUBLIC KEY-----\n{lines}-----END PUBLIC KEY-----";
}

bool VerifyTimestamp(string timestamp)
{
    if (!long.TryParse(timestamp, out var ts)) return false;
    var requestTime = DateTimeOffset.FromUnixTimeSeconds(ts);
    var diffMinutes = Math.Abs((DateTimeOffset.UtcNow - requestTime).TotalMinutes);
    return diffMinutes <= MaxAgeMinutes;
}

bool VerifySignature(string rawBody, string signatureBase64, string timestamp)
{
    try
    {
        // The signed message is `${timestamp}.${rawBody}`, pre-hashed with SHA-256.
        // RSA.VerifyData below hashes again, matching the Node/Python implementations
        // (which feed a SHA-256 digest into an RSA-SHA256 verifier).
        var message = $"{timestamp}.{rawBody}";
        var digest = SHA256.HashData(Encoding.UTF8.GetBytes(message));
        var signature = Convert.FromBase64String(signatureBase64);

        using var rsa = RSA.Create();
        rsa.ImportFromPem(ToPem(PublicKey));

        return rsa.VerifyData(
            digest,
            signature,
            HashAlgorithmName.SHA256,
            RSASignaturePadding.Pkcs1);
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"Signature verification error: {ex.Message}");
        return false;
    }
}

app.MapPost("/webhooks/hercle", async (HttpRequest request) =>
{
    // Read the raw body exactly as received — do not re-serialize
    using var reader = new StreamReader(request.Body, Encoding.UTF8);
    var rawBody = await reader.ReadToEndAsync();

    var signature = request.Headers["X-Webhook-Signature"].ToString();
    var timestamp = request.Headers["X-Webhook-Timestamp"].ToString();
    var webhookId = request.Headers["X-Webhook-Id"].ToString();

    if (!VerifyTimestamp(timestamp))
        return Results.BadRequest(new { error = "Timestamp too old or invalid" });

    if (!VerifySignature(rawBody, signature, timestamp))
        return Results.BadRequest(new { error = "Invalid signature" });

    var payload = JsonSerializer.Deserialize<JsonElement>(rawBody);
    var eventType = payload.GetProperty("eventType").GetString();
    var eventId = payload.GetProperty("eventId").GetString();

    Console.WriteLine($"Webhook verified: {eventType} ({eventId})");

    // Event data is already a parsed object — no extra deserialization needed
    var eventData = payload.GetProperty("data");

    // Handle the event based on type
    switch (eventType)
    {
        case "Banking.Deposit.StatusUpdated":
            // HandleDeposit(eventData);
            break;
        case "VirtualAccount.Registered":
            // HandleVirtualAccount(eventData);
            break;
        // ... handle other event types
    }

    // Always return 200 to acknowledge receipt
    return Results.Ok(new { success = true });
});

app.Run();

app.post('/webhooks/hercle', async (req, res) => {
  // Verify signature first
  if (!verifySignature(...)) {
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Acknowledge immediately
  res.status(200).json({ success: true });

  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});

const processedEvents = new Set(); // Use a database in production

function handleWebhook(payload) {
  if (processedEvents.has(payload.eventId)) {
    console.log('Event already processed:', payload.eventId);
    return;
  }

  processedEvents.add(payload.eventId);
  // Process the event...
}

console.log('Received webhook:', {
  webhookId: req.get('X-Webhook-Id'),
  eventId: payload.eventId,
  eventType: payload.eventType,
});