Appearance

Webhooks & Sync PREMIUM ​

This guide explains how webhooks work within Banclo's offline architecture, enabling real-time integration between offline instances and your internal systems. Webhooks provide event-driven notifications that help maintain operational efficiency even when working in offline mode.

Overview ​

Webhooks in the Business Continuity Suite create a complete integration loop where Banclo Cloud synchronizes data to offline instances, which then trigger webhooks to notify your internal systems. These internal systems can then use OAuth clients to fetch additional data or perform related operations, creating a seamless data flow.

This architecture ensures that critical business events are communicated immediately to your internal systems, whether they originate from cloud operations or offline instances. The webhook system maintains the same reliability and security standards across all deployment modes.

Webhook Architecture ​

The webhook system operates within a comprehensive data flow that connects cloud services, offline instances, and internal systems:

Data Flow Explanation ​

This comprehensive architecture demonstrates how webhooks create a complete integration ecosystem:

1. Cloud to Offline Sync: Banclo Cloud initiates scheduled synchronization, encrypting and transferring data to all offline instances based on their configured sync schedules.

2. Local Event Processing: Each offline instance processes incoming data changes and generates local events for significant business activities such as loan status changes, document uploads, or client updates.

3. Webhook Triggers: When events occur, the offline instance immediately sends webhook notifications to configured internal systems, regardless of whether the event originated from cloud sync or local user activity.

4. OAuth Authentication: Internal systems receive webhook notifications and use their OAuth client credentials to authenticate with the offline instance for additional data access.

5. API Data Requests: Authenticated internal systems make API calls to fetch additional context, related records, or perform supplementary operations based on the webhook event.

6. Business Process Completion: The combination of webhook notifications and API data access enables internal systems to complete their business processes, maintain data consistency, and trigger any necessary downstream operations.

This architecture ensures that your internal systems remain responsive and informed regardless of connectivity status, creating a resilient integration ecosystem that works seamlessly across online and offline modes.

Webhook Events ​

The Business Continuity Suite supports a focused set of webhook events for essential loan origination activities:

Available Events ​

  • loan_request.created - New loan application submitted
  • loan_request.status_changed - Loan status transition (e.g., pending → approved → completed)
  • bid.accepted - Loan bid has been accepted
  • task.completed - Task marked as finished
  • message.received - New message received in loan communication

Configuring Webhooks ​

Creating Webhook Endpoints ​

Webhooks are configured through your Business Continuity Suite's settings interface:

  1. Access Settings: Navigate to your Business Continuity Suite web interface
  2. Webhooks: Go to Settings → Webhooks
  3. Add Webhook: Click "Add Webhook"
  4. Configure Webhook:
    • Name: Descriptive name for the webhook
    • Description: Optional description of the webhook's purpose
    • Endpoint URL: Your internal system's webhook receiver URL
    • Type: HTTP, Slack, or Teams webhook
    • Events: Select from available events
    • Authentication: Optional security configuration
    • Status: Active/Inactive toggle

Webhook Payload Structure ​

All webhook requests follow a consistent JSON format with event-specific data:

Standard Payload Structure ​

json
{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T14:30:00Z",
  "eventType": "loan_request.created",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "K0Z1Q", 
    "entityType": "LoanRequest",
    "metadata": {
      // Event-specific metadata (see examples below)
    }
  },
  "security": {
    "signature": "sha256=abcdef123456...",
    "timestamp": 1705315800
  }
}

Event-Specific Payloads ​

1. loan_request.created ​

json
{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T14:30:00Z",
  "eventType": "loan_request.created",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "K0Z1Q",
    "entityType": "LoanRequest",
    "metadata": {
      "applicationId": "APP-2024-001",
      "status": "PRE_BID",
      "bankHashid": "B1A2C3",
      "principalAmount": 250000,
      "currency": "EUR",
      "created": true,
      "syncVersion": 1
    }
  }
}

2. loan_request.status_changed ​

json
{
  "id": "evt_660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2024-01-15T15:45:00Z",
  "eventType": "loan_request.status_changed",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "K0Z1Q",
    "entityType": "LoanRequest",
    "metadata": {
      "applicationId": "APP-2024-001",
      "previousStatus": "PRE_BID",
      "newStatus": "BID",
      "bankHashid": "B1A2C3",
      "principalAmount": 250000,
      "currency": "EUR",
      "syncVersion": 2
    }
  }
}

3. bid.accepted ​

json
{
  "id": "evt_770e8400-e29b-41d4-a716-446655440002",
  "timestamp": "2024-01-15T16:20:00Z",
  "eventType": "bid.accepted",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "074P0",
    "entityType": "LoanBid",
    "metadata": {
      "bankName": "Example Bank",
      "bankAcronym": "EXB",
      "principalAmount": 240000,
      "totalPrincipalAmount": 240000,
      "acceptedOn": "2024-01-15T16:19:30Z",
      "facilitiesCount": 1
    }
  }
}

4. task.completed ​

json
{
  "id": "evt_880e8400-e29b-41d4-a716-446655440003",
  "timestamp": "2024-01-15T17:10:00Z",
  "eventType": "task.completed",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "T5K8L2",
    "entityType": "Task",
    "metadata": {
      "taskName": "Employment Verification",
      "taskSlug": "employment_verification",
      "assigneeHashid": "U9X4Y7",
      "assigneeName": "John Smith",
      "completedAt": "2024-01-15T17:09:45Z",
      "dueDate": "2024-01-16T23:59:59Z",
      "previousStatus": "IN_PROGRESS",
      "isNewTask": false
    }
  }
}

5. message.received ​

json
{
  "id": "evt_990e8400-e29b-41d4-a716-446655440004",
  "timestamp": "2024-01-15T18:05:00Z",
  "eventType": "message.received",
  "version": "1.0",
  "source": {
    "system": "banclo-offline",
    "instanceId": "your-instance-id",
    "environment": "production"
  },
  "data": {
    "loanRequestHashid": "K0Z1Q",
    "entityHashid": "M3R7N9",
    "entityType": "Message",
    "metadata": {
      "channelHashid": "C6H2V8",
      "authorType": "CLIENT",
      "authorName": "Jane Doe",
      "authorEmail": "[email protected]",
      "hasAttachments": true,
      "attachmentCount": 2
    }
  }
}