Beneficiary Status Change Webhook

Overview

The BENEFICIARY_STATUS_CHANGE webhook is triggered when a beneficiary's compliance screening, AML evaluation, or approval state transitions (e.g. moving from Pending Verification to Approved or Rejected).

Webhook Delivery

• HTTP Method: POST
• Destination: Your configured server webhook endpoint
• Content-Type: application/json

Webhook Headers

Header	Value	Description
Content-Type	application/json	Request body media type
x-webhook-event	BENEFICIARY_STATUS_CHANGE	Identifier of the dispatched event type
x-webhook-timestamp	ISO 8601 string	Timestamp when the event was dispatched

Event Payload

{
  "beneficiaryId": "bnf_102938",
  "oldStatus": "Pending Verification",
  "newStatus": "Approved",
  "updatedAt": "2025-03-21T09:45:00Z"
}

Payload Fields

Field	Type	Required	Description
beneficiaryId	string	Yes	Unique identifier of the beneficiary profile.
oldStatus	string	Yes	The preceding verification or review status (e.g. Pending Verification).
newStatus	string	Yes	The updated status after compliance review (e.g. Approved, Rejected).
updatedAt	string (ISO Date)	Yes	UTC timestamp when the state transition occurred.

Expected Server Response

Return an HTTP 200 OK status to acknowledge receipt:

{
  "received": true
}

Implementation Examples

Node.js (Express)

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

app.use(express.json());

app.post('/webhook', (req, res) => {
  const eventType = req.headers['x-webhook-event'];
  const { beneficiaryId, oldStatus, newStatus, updatedAt } = req.body;

  if (eventType === 'BENEFICIARY_STATUS_CHANGE') {
    console.log(`Beneficiary ${beneficiaryId} status updated from ${oldStatus} to ${newStatus} at ${updatedAt}`);
    // Enable or disable payout execution depending on approval status
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Beneficiary Webhook listener running on port 3000'));

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event_type = request.headers.get('x-webhook-event')
    data = request.json or {}

    if event_type == 'BENEFICIARY_STATUS_CHANGE':
        beneficiary_id = data.get('beneficiaryId')
        old_status = data.get('oldStatus')
        new_status = data.get('newStatus')
        updated_at = data.get('updatedAt')
        print(f"Beneficiary {beneficiary_id} transitioned from {old_status} to {new_status} at {updated_at}")
        # Enable or disable payout workflows depending on approval status

    return jsonify({"received": True}), 200

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

Interactive Webhook Schema Explorer