Webhooks Guide

Webhooks let your application receive real-time HTTP notifications when events occur in Banklyze — deals created, documents processed, batches completed, and more.

Overview

Instead of polling the API for status changes, you configure a webhook endpoint URL where Banklyze will send POST requests for each event. Each delivery includes a JSON payload describing the event and an HMAC-SHA256 signature for verification.

Example webhook payload

{
  "id": "evt_abc123",
  "type": "deal.ready",
  "created_at": "2025-01-15T14:30:00Z",
  "data": {
    "deal_id": 42,
    "business_name": "Acme Trucking LLC",
    "status": "ready",
    "health_score": 72.5
  }
}

Event Catalog

Subscribe to any combination of these events when configuring your webhook:

Event Type	Trigger
deal.created	A new deal is created.
deal.updated	A deal is updated (status, fields, or notes).
deal.ready	All documents for a deal have been processed and the deal is ready for review.
deal.decision	An underwriting decision (approved, declined, more_info) is recorded.
document.uploaded	A document is uploaded and queued for processing.
document.completed	Document processing finished successfully.
document.failed	Document processing encountered an error.
batch.completed	All documents in a bulk ingest batch have finished processing.
recommendation.generated	An underwriting recommendation has been generated for a deal.
export.ready	A requested export file (PDF/CSV) is ready for download.

Webhook Configuration

Configure your webhook endpoint by sending a POST request to /v1/webhooks/config. You provide the target URL, a signing secret, and the list of events you want to receive.

Name	Type	Required	Description
url	string	Required	The HTTPS URL where webhook deliveries will be sent.
secret	string	Required	A shared secret used for HMAC-SHA256 signature verification.
events	string[]	Required	Array of event types to subscribe to.
active	boolean	Default: true	Whether the webhook is active. Defaults to true.

curl -X POST "https://api.banklyze.com/v1/webhooks/config" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/banklyze",
    "secret": "whsec_your_signing_secret",
    "events": [
      "deal.created",
      "deal.ready",
      "document.completed",
      "batch.completed"
    ],
    "active": true
  }'

Your webhook URL must use HTTPS. HTTP endpoints are rejected for security.

Signature Verification

Every webhook delivery includes an X-Banklyze-Signature header containing an HMAC-SHA256 signature of the raw request body. Always verify this signature before processing the payload.

Name	Type	Required	Description
X-Banklyze-Signature	string	Required	HMAC-SHA256 signature in the format sha256=<hex_digest>. Computed over the raw request body using your webhook secret.

#!/bin/bash
# Verify webhook signature with openssl
SECRET="whsec_your_signing_secret"
PAYLOAD='{"id":"evt_abc123","type":"deal.ready",...}'
SIGNATURE="sha256=a1b2c3..."

EXPECTED="sha256=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"

if [ "$SIGNATURE" = "$EXPECTED" ]; then
  echo "Signature valid"
else
  echo "Signature INVALID — reject this delivery"
  exit 1
fi

Never skip signature verification. Without it, an attacker could send forged webhook deliveries to your endpoint.

Retry Behavior

If your endpoint returns a non-2xx status code or the connection times out, Banklyze retries the delivery up to 3 times with exponential backoff:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	15 minutes

Your endpoint should respond within 10 seconds. If processing takes longer, return a 202 Accepted immediately and handle the event asynchronously.

Your webhook handler must be idempotent. Banklyze may deliver the same event more than once due to retries or network issues. Use the event id field to deduplicate.

Delivery Logs

Inspect recent webhook deliveries, including status codes and timestamps, via the delivery logs endpoint:

List delivery logs

curl -s \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  "https://api.banklyze.com/v1/webhooks/deliveries?per_page=10"

# Response:
# {
#   "data": [
#     {
#       "id": "dlv_xyz789",
#       "event_type": "deal.ready",
#       "url": "https://your-app.com/webhooks/banklyze",
#       "status_code": 200,
#       "success": true,
#       "attempt": 1,
#       "delivered_at": "2025-01-15T14:30:01Z"
#     }
#   ],
#   "meta": { "page": 1, "per_page": 10, "total": 47, "total_pages": 5 }
# }

Testing Webhooks

Send a test event to your configured endpoint to verify connectivity and signature validation:

Send test webhook

# Send a test event to your webhook endpoint
curl -X POST "https://api.banklyze.com/v1/webhooks/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "deal.ready" }'

During development, use a tool like ngrok to expose your local server to the internet for webhook testing.

Share Links

SDKs & Libraries