Skip to main content

​
Overview

FinPro webhooks deliver real-time HTTP POST notifications to your server when consent and data lifecycle events occur. Instead of polling the FinPro APIs for status changes, your application receives instant updates as events happen — such as when a user approves a consent, data becomes ready for fetch, or a session expires. Use webhooks when you need to:
  • React immediately to consent approvals (e.g., trigger an FI Request)
  • Know the moment financial data is ready for retrieval
  • Track consent revocations, pauses, and expirations
  • Receive raw financial data pushed directly via DATA_PUSH events

​
Configuration

Set up webhooks through the FinPro Admin Portal:
1

Navigate to Webhooks

Log in to the Admin Portal and navigate to Admin → Webhooks.
2

Configure your endpoint

Provide:
  • Webhook URL — Your HTTPS endpoint that will receive event notifications
  • Secret Key — A shared secret used for HMAC-SHA256 signature verification
  • App Identifier — The application/product identifier to scope events
3

Subscribe to event categories

Select the event categories you want to receive:
  • CONSENT — Consent lifecycle events (approved, rejected, paused, resumed, revoked, expired)
  • DATA — Data fetch events (ready, denied, session failed, session expired)
  • DATA_EXT — Extended data events (DATA_PUSH with inline financial data)

​
Common Payload Structure

All webhook events are sent as JSON POST requests with these common fields:
FieldTypeDescription
timestampstringISO 8601 timestamp of when the event occurred
consentHandlestringUUID identifying the consent request
eventTypestringEvent category: CONSENT, DATA, or DATA_EXT
eventStatusstringSpecific event status (e.g., CONSENT_APPROVED, DATA_READY)
consentIdstringUUID of the consent artifact (may be empty for rejected consents)
vuastringVirtual User Address of the user (e.g., 9999999999@onemoney)
eventMessagestringHuman-readable description of the event

​
Extended Payload Fields (Type 2)

Type 2 payloads include additional fields for richer event context:
FieldTypeDescription
productIDstringProduct identifier configured in the Admin Portal
accountIDstringAccount identifier associated with the consent request
fetchTypestringConsent fetch type: ONETIME or PERIODIC
consentExpirystringConsent expiry datetime
Data events may also include:
FieldTypeDescription
dataExpirystringISO 8601 timestamp when fetched data expires
firstTimeFetchbooleanWhether this is the first data fetch for this consent
sessionIdstringSession identifier (present in SESSION_FAILED events)

​
Webhook Verification (HMAC-SHA256)

Every webhook request includes an X-Webhook-Signature header containing a Base64-encoded HMAC-SHA256 signature. Verify this signature to confirm the request originated from FinPro and was not tampered with. How it works:
  1. FinPro serializes the JSON payload body to a string
  2. Computes HMAC-SHA256(JSON.stringify(payload), your_secret_key)
  3. Base64-encodes the result
  4. Sends it in the X-Webhook-Signature header
To verify, compute the same HMAC-SHA256 hash on the raw request body and compare it to the header value. 
const crypto = require("crypto");

function verifyWebhookSignature(rawBody, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac("sha256", secretKey)
    .update(rawBody)
    .digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const rawBody = req.body.toString();

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);
  // Process the event...
  res.status(200).send("OK");
});

​
Event Categories

CategoryeventTypeEventsDescription
ConsentCONSENTCONSENT_APPROVED, CONSENT_REJECTED, CONSENT_PAUSED, CONSENT_RESUMED, CONSENT_REVOKED, CONSENT_EXPIREDConsent lifecycle state changes
DataDATADATA_READY, DATA_DENIED, SESSION_FAILED, SESSION_EXPIREDData fetch status updates
Data ExtendedDATA_EXTDATA_PUSHInline data delivery with full FI payloads
See Consent Events and Data Events for detailed payload documentation.

​
Endpoint Requirements

Your webhook endpoint must meet the following requirements:
RequirementDetails
ProtocolHTTPS only
HTTP MethodAccept POST requests
Content-TypeHandle application/json payloads
ResponseReturn HTTP 200 status to acknowledge receipt
Response TimeRespond within 10 seconds
If your endpoint does not return HTTP 200, FinPro will retry the webhook delivery up to 5 times.

​
Best Practices

  • Always verify signatures — Validate the X-Webhook-Signature header on every request using HMAC-SHA256
  • Use HTTPS only — Never expose webhook endpoints over plain HTTP
  • Keep secrets secure — Store your webhook secret key in environment variables, not in source code
  • Validate payloads — Check that eventType and eventStatus values are expected before processing
  • Respond quickly — Return HTTP 200 immediately, then process the event asynchronously
  • Handle retries — FinPro retries failed deliveries up to 5 times, so your endpoint may receive the same event more than once
  • Idempotency — Use the consentHandle + eventStatus + timestamp combination to detect and deduplicate repeated deliveries
  • Queue processing — For high-volume integrations, enqueue events for background processing rather than handling inline
  • Log all events — Record incoming webhook payloads for debugging and audit trails
  • Alert on failures — Monitor your endpoint’s error rate and response times
  • Track event types — Monitor which events you receive to verify your subscription is configured correctly