{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "payment.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:15:00+00:00",
  "client_id": "your-client-uuid",
  "data": {
    // Event-specific fields - see below
  }
}

import hmac
import hashlib
import time

def verify_webhook(payload_body: bytes, signature_header: str,
                   timestamp_header: str, webhook_secret: str,
                   max_age_seconds: int = 300) -> bool:
    """Verify an UrbanPay webhook signature."""
    # 1. Check timestamp freshness to prevent replay attacks
    try:
        event_time = int(timestamp_header)
    except (ValueError, TypeError):
        return False

    if abs(time.time() - event_time) > max_age_seconds:
        return False

    # 2. Compute expected signature
    signing_payload = f"{timestamp_header}.".encode("utf-8") + payload_body
    expected = hmac.new(
        webhook_secret.encode("utf-8"),
        signing_payload,
        hashlib.sha256
    ).hexdigest()

    # 3. Compare signatures (constant-time to prevent timing attacks)
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

const crypto = require("crypto");

function verifyWebhook(payloadBody, signatureHeader, timestampHeader,
                       webhookSecret, maxAgeSeconds = 300) {
  // 1. Check timestamp freshness
  const eventTime = parseInt(timestampHeader, 10);
  if (isNaN(eventTime)) return false;
  if (Math.abs(Date.now() / 1000 - eventTime) > maxAgeSeconds) return false;

  // 2. Compute expected signature
  const signingPayload = `${timestampHeader}.${payloadBody}`;
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(signingPayload)
    .digest("hex");

  // 3. Compare signatures (constant-time)
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

{
  "id": "evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:15:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "transaction_id": "tx-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "ref_id": "abc123def456",
    "transfer_id": "payment-network-transfer-id-789",
    "amount": "125.00",
    "currency": "EUR",
    "user_id": "usr-11111111-2222-3333-4444-555555555555",
    "business_customer_id": null,
    "project_id": "prj-11111111-2222-3333-4444-555555555555",
    "contract_request_id": null,
    "previous_payment_status": "pending",
    "current_payment_status": "processing",
    "reconciliation_state": "none",
    "status_detail": "awaiting_bank_authorization",
    "status_reason": null,
    "actor_type": null,
    "actor_account_id": null
  }
}

{
  "id": "evt-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "kyc.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:20:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "user_id": "usr-11111111-2222-3333-4444-555555555555",
    "email": "[email protected]",
    "verification_mode": "urbanpayx_kyc",
    "previous_kyc_status": "pending",
    "current_kyc_status": "approved",
    "previous_external_status": "pending",
    "current_external_status": "pending",
    "previous_verification_source": "urbanpayx",
    "current_verification_source": "urbanpayx",
    "source": "provider_webhook"
  }
}

{
  "id": "evt-c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "opco.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:25:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "opco_id": "opc-11111111-2222-3333-4444-555555555555",
    "sub_tpp_id": "sub-tpp-identifier",
    "name": "Acme Properties Ltd",
    "previous_opco_status": "awaiting_approval",
    "current_opco_status": "activated",
    "opco_status_reason": null
  }
}

{
  "id": "evt-d4e5f6a7-b8c9-0123-defa-234567890123",
  "type": "project.frozen_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:30:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "project_id": "prj-11111111-2222-3333-4444-555555555555",
    "project_name": "Sunrise Apartments",
    "previous_is_frozen": false,
    "current_is_frozen": true,
    "source": "admin",
    "actor_type": "superadmin",
    "actor_id": "admin-uuid"
  }
}

{
  "id": "evt-f6a7b8c9-d0e1-2345-fabc-456789012345",
  "type": "kyb.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:40:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "business_customer_id": "bcu-11111111-2222-3333-4444-555555555555",
    "company_name": "Acme Holdings Ltd",
    "registration_number": "12345678",
    "country": "GB",
    "verification_mode": "urbanpayx_kyb",
    "previous_kyb_status": "pending",
    "current_kyb_status": "approved",
    "previous_external_status": "pending",
    "current_external_status": "pending",
    "previous_verification_source": "urbanpayx",
    "current_verification_source": "urbanpayx"
  }
}

{
  "id": "evt-a7b8c9d0-e1f2-3456-abcd-567890123456",
  "type": "monitoring.transaction.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:45:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "monitored_transaction_id": "mtx-11111111-2222-3333-4444-555555555555",
    "client_reference": "order-4821",
    "previous_decision": "IN_REVIEW",
    "decision": "APPROVED",
    "decision_reason": null,
    "sanctions_hit": false,
    "remediation_url": null,
    "remediation_status": null
  }
}

{
  "id": "evt-b8c9d0e1-f2a3-4567-bcde-678901234567",
  "type": "workflow.run.completed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:50:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "run_id": "wfr-11111111-2222-3333-4444-555555555555",
    "workflow_definition_id": "wf-11111111-2222-3333-4444-555555555555"
  }
}

{
  "id": "evt-c9d0e1f2-a3b4-5678-cdef-789012345678",
  "type": "workflow.step.completed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:52:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "run_id": "wfr-11111111-2222-3333-4444-555555555555",
    "step_id": "create-project",
    "node_type": "project",
    "output": {}
  }
}

{
  "id": "evt-e5f6a7b8-c9d0-1234-efab-345678901234",
  "type": "webhook.test",
  "version": "v1",
  "occurred_at": "2026-03-26T10:35:00+00:00",
  "client_id": "cl-11111111-2222-3333-4444-555555555555",
  "data": {
    "message": "UrbanPay webhook test event",
    "requested_by_account_id": "acc-11111111-2222-3333-4444-555555555555"
  }
}

import hmac
import hashlib
import time
import json
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "upxwhsec_your_secret_here"
processed_events = set()  # Use a database in production

@app.route("/webhooks/urbanpayx", methods=["POST"])
def handle_webhook():
    # 1. Get headers
    signature = request.headers.get("X-UPX-Signature", "")
    timestamp = request.headers.get("X-UPX-Timestamp", "")
    event_id = request.headers.get("X-UPX-Event-Id", "")

    # 2. Verify signature
    payload_body = request.get_data()
    signing_payload = f"{timestamp}.".encode("utf-8") + payload_body
    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"), signing_payload, hashlib.sha256
    ).hexdigest()
    received = signature.removeprefix("sha256=")

    if not hmac.compare_digest(expected, received):
        return jsonify({"error": "Invalid signature"}), 401

    # 3. Check timestamp freshness (5 minutes)
    if abs(time.time() - int(timestamp)) > 300:
        return jsonify({"error": "Event too old"}), 401

    # 4. Deduplicate
    if event_id in processed_events:
        return jsonify({"status": "already_processed"}), 200

    # 5. Parse and route
    event = json.loads(payload_body)
    event_type = event["type"]
    data = event["data"]

    if event_type == "payment.status_changed":
        handle_payment_status(data)
    elif event_type == "kyc.status_changed":
        handle_kyc_status(data)
    elif event_type == "opco.status_changed":
        handle_opco_status(data)
    elif event_type == "project.frozen_changed":
        handle_project_frozen(data)
    elif event_type == "webhook.test":
        pass  # Acknowledge test events

    processed_events.add(event_id)
    return jsonify({"status": "ok"}), 200

def handle_payment_status(data):
    status = data["current_payment_status"]
    if status == "success":
        # Mark order as paid, trigger fulfillment
        pass
    elif status == "failed":
        # Notify customer, offer retry
        pass
    elif status == "expired":
        # Offer new payment link
        pass
    elif status == "canceled":
        # Update order status
        pass

def handle_kyc_status(data):
    if data["current_kyc_status"] == "approved":
        # Update your own records. The API itself never blocks payments on
        # verification status -- this check is purely your own policy, if any.
        pass
    elif data["current_kyc_status"] == "rejected":
        # Notify user, explain next steps
        pass

def handle_opco_status(data):
    if data["current_opco_status"] == "activated":
        # OpCo is ready - you can now create projects and payments
        pass
    elif data["current_opco_status"] == "rejected":
        # Check opco_status_reason, create a new OpCo with corrections
        pass

def handle_project_frozen(data):
    if data["current_is_frozen"]:
        # Stop creating payments for this project
        pass

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

const app = express();
const WEBHOOK_SECRET = "upxwhsec_your_secret_here";
const processedEvents = new Set(); // Use a database in production

app.post("/webhooks/urbanpayx", express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-upx-signature"] || "";
    const timestamp = req.headers["x-upx-timestamp"] || "";
    const eventId = req.headers["x-upx-event-id"] || "";
    const payloadBody = req.body.toString();

    // 1. Verify signature
    const signingPayload = `${timestamp}.${payloadBody}`;
    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(signingPayload)
      .digest("hex");
    const received = signature.replace("sha256=", "");

    if (!crypto.timingSafeEqual(
      Buffer.from(expected, "hex"), Buffer.from(received, "hex")
    )) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    // 2. Check timestamp freshness
    if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
      return res.status(401).json({ error: "Event too old" });
    }

    // 3. Deduplicate
    if (processedEvents.has(eventId)) {
      return res.status(200).json({ status: "already_processed" });
    }

    // 4. Parse and route
    const event = JSON.parse(payloadBody);
    const { type, data } = event;

    switch (type) {
      case "payment.status_changed":
        handlePaymentStatus(data);
        break;
      case "kyc.status_changed":
        handleKycStatus(data);
        break;
      case "opco.status_changed":
        handleOpcoStatus(data);
        break;
      case "project.frozen_changed":
        handleProjectFrozen(data);
        break;
      case "webhook.test":
        break;
    }

    processedEvents.add(eventId);
    res.status(200).json({ status: "ok" });
  }
);

function handlePaymentStatus(data) {
  switch (data.current_payment_status) {
    case "success":  /* Mark order paid */ break;
    case "failed":   /* Notify customer */ break;
    case "expired":  /* Offer new link */  break;
    case "canceled": /* Update status */   break;
  }
}

function handleKycStatus(data) {
  if (data.current_kyc_status === "approved") {
    // User verified
  } else if (data.current_kyc_status === "rejected") {
    // Notify user
  }
}

function handleOpcoStatus(data) {
  if (data.current_opco_status === "activated") {
    // OpCo ready
  }
}

function handleProjectFrozen(data) {
  if (data.current_is_frozen) {
    // Pause payment creation
  }
}

app.listen(3000, () => console.log("Webhook handler running on port 3000"));