Skip to main content

​
Overview

Credzu sends webhook callbacks (HTTP POST requests) to your registered endpoint whenever a significant event occurs for a lead. This allows your system to stay synchronized with borrower progress without polling.

​
How Webhooks Work

  1. When you onboard as a partner, you provide Credzu with your webhook URL
  2. When events occur for your leads, Credzu sends a POST request to your URL
  3. Your server processes the event and returns a 200 OK response
  4. If delivery fails, Credzu retries with exponential backoff

​
Webhook Payload Structure

All webhook payloads follow this structure: 
{
  "event": "event_name",
  "timestamp": "2025-01-22T17:38:12Z",
  "lead_id": 44921,
  "partner_lead_id": "FBHL-55672",
  "details": {}
}
FieldTypeDescription
eventstringThe event type (e.g., contract_signed, mortgage_ready)
timestampstringISO 8601 timestamp when the event occurred
lead_idintegerCredzu’s unique identifier for the lead
partner_lead_idstringYour internal ID (if provided when creating the lead)
detailsobjectEvent-specific data (varies by event type)

​
Available Events

EventDescriptionPriority
lead_receivedLead was successfully createdLow
client_account_createdBorrower completed onboardingMedium
credit_scan_completedBorrower completed credit scanMedium
client_engaged_in_chatBorrower sent messagesLow
contract_signedBorrower signed service contractHigh
escrow_fundedBorrower funded escrow accountHigh
score_updateCredit score update (every 45 days)High
mortgage_readyBorrower is ready to returnCritical

​
Implementing Your Webhook Endpoint

Your endpoint must:
  • Accept POST requests with Content-Type: application/json
  • Return 200 OK to acknowledge receipt
  • Process events asynchronously if needed (respond quickly, process later)

​
Example Implementation (PHP)

<?php
// webhook.php

// Read raw POST body
$raw = file_get_contents("php://input");
$data = json_decode($raw, true);

// Log for debugging
file_put_contents("credzu-webhook.log", date("c") . " " . $raw . "\n", FILE_APPEND);

// Validate payload
if (!isset($data["event"]) || !isset($data["lead_id"])) {
    http_response_code(400);
    echo json_encode(array("success" => false, "message" => "Invalid payload"));
    exit;
}

// Process event
switch ($data["event"]) {
    case "lead_received":
        // Update CRM to show lead was received
        break;
    case "client_account_created":
        // Borrower is engaged
        break;
    case "credit_scan_completed":
        // Credit data available
        break;
    case "contract_signed":
        // Borrower committed
        break;
    case "escrow_funded":
        // Serious engagement
        break;
    case "score_update":
        // Update dashboard with score improvements
        $gains = $data["details"];
        break;
    case "mortgage_ready":
        // ALERT LOAN OFFICER - highest priority
        break;
}

// Return 200 OK
http_response_code(200);
echo json_encode(array("success" => true));

​
Retry Logic

If your endpoint fails to respond with 200 OK:
AttemptDelayAction
1ImmediateFirst attempt
25 secondsRetry
320 secondsRetry
460 secondsFinal retry
After 3 failed retries:
  • The webhook is marked as failed
  • Credzu support is notified
  • You can retrieve missed events using Get Events
Ensure your webhook endpoint is reliable and responds quickly. Slow responses or downtime can cause missed events.

​
Security Considerations

1

Use HTTPS

Your webhook URL must use HTTPS for secure data transmission.
2

Validate the payload

Check that required fields (event, lead_id) are present before processing.
3

Verify the lead belongs to you

Cross-reference the partner_lead_id with your records.
4

Process asynchronously

Return 200 OK immediately, then process the event in the background.

​
Testing Webhooks

In the sandbox environment, you can:
  • Trigger simulated events for your test leads
  • Verify your webhook endpoint is receiving and processing events correctly
  • Test retry logic by temporarily returning error responses
Contact Credzu support to configure your webhook URL or update it for a new integration.