Webhooks Config API

Configure a webhook endpoint to receive real-time notifications when events occur in your Banklyze account. Subscribe to specific event types, test delivery, and inspect the full request/response log for every delivery attempt.

Available events: deal.created, deal.updated, deal.ready, deal.decision, document.uploaded, document.completed, document.failed, batch.completed, recommendation.generated, export.ready.

Get Webhook Config

Returns the current webhook configuration, including the endpoint URL, subscribed events, and enabled status. The signing secret is not returned in the response.

Request

curl https://api.banklyze.com/v1/webhooks/config \
  -H "Authorization: Bearer bkz_live_abc123"

200 OK

{
  "data": {
    "url": "https://yourapp.com/webhooks/banklyze",
    "events": [
      "deal.created",
      "deal.ready",
      "deal.decision",
      "document.completed",
      "document.failed",
      "batch.completed",
      "recommendation.generated"
    ],
    "enabled": true,
    "created_at": "2025-10-01T08:00:00Z",
    "updated_at": "2025-10-15T12:30:00Z"
  }
}

Set Webhook Config

Creates or replaces the webhook configuration. The signing secret is used to generate HMAC-SHA256 signatures sent in the X-Banklyze-Signature header of each delivery.

Name	Type	Required	Description
url	string	Required	HTTPS URL to receive webhook POST requests
secret	string	Required	Signing secret for HMAC-SHA256 signature verification
events	string[]	Required	Array of event types to subscribe to
enabled	boolean	Default: true	Whether to deliver webhooks

Request

curl -X PUT https://api.banklyze.com/v1/webhooks/config \
  -H "Authorization: Bearer bkz_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/banklyze",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "events": [
      "deal.created",
      "deal.ready",
      "deal.decision",
      "document.completed",
      "document.failed",
      "batch.completed",
      "recommendation.generated"
    ],
    "enabled": true
  }'

200 OK

{
  "data": {
    "url": "https://yourapp.com/webhooks/banklyze",
    "events": [
      "deal.created",
      "deal.ready",
      "deal.decision",
      "document.completed",
      "document.failed",
      "batch.completed",
      "recommendation.generated"
    ],
    "enabled": true,
    "created_at": "2025-10-01T08:00:00Z",
    "updated_at": "2025-11-01T14:30:00Z"
  }
}

Clear Webhook Config

Removes the webhook configuration. No further webhook deliveries will be attempted until a new configuration is set.

Request

curl -X DELETE https://api.banklyze.com/v1/webhooks/config \
  -H "Authorization: Bearer bkz_live_abc123"

200 OK

{
  "success": true,
  "message": "Webhook config cleared"
}

Test Webhook

Sends a test event to the configured webhook URL and returns the delivery result. Use this to verify your endpoint is reachable and correctly validating signatures before going live.

Request

curl -X POST https://api.banklyze.com/v1/webhooks/test \
  -H "Authorization: Bearer bkz_live_abc123"

200 OK

{
  "data": {
    "delivery_id": "dlv_01JE7K8X2M3N4P5Q6R7S",
    "event": "webhook.test",
    "status": "delivered",
    "response_status": 200,
    "response_time_ms": 142,
    "delivered_at": "2025-11-01T14:30:01Z"
  }
}

List Delivery Logs

Returns a paginated list of webhook delivery attempts with status, event type, and timing information. Filter by event type or delivery status.

Name	Type	Required	Description
page	integer	Default: 1	Page number
per_page	integer	Default: 25	Results per page (1-100)
event	string	Optional	Filter by event type (e.g. deal.ready)
status	string	Optional	Filter by delivery status: delivered, failed, pending

Request

curl "https://api.banklyze.com/v1/webhooks/deliveries?page=1&per_page=10&event=deal.ready&status=delivered" \
  -H "Authorization: Bearer bkz_live_abc123"

200 OK

{
  "data": [
    {
      "id": "dlv_01JE7K8X2M3N4P5Q6R7S",
      "event": "deal.ready",
      "status": "delivered",
      "response_status": 200,
      "attempt_number": 1,
      "created_at": "2025-11-01T14:32:45Z",
      "delivered_at": "2025-11-01T14:32:45Z"
    },
    {
      "id": "dlv_01JE6H7W1L2M3N4O5P6Q",
      "event": "deal.ready",
      "status": "delivered",
      "response_status": 200,
      "attempt_number": 1,
      "created_at": "2025-10-30T09:15:22Z",
      "delivered_at": "2025-10-30T09:15:23Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "total_pages": 1
  }
}

Delivery Detail

Returns the full details of a specific delivery attempt, including the request body, headers, response body, response status code, timing, and attempt number. Useful for debugging failed deliveries.

Name	Type	Required	Description
delivery_id	string	Required	The delivery ID

Request

curl https://api.banklyze.com/v1/webhooks/deliveries/dlv_01JE7K8X2M3N4P5Q6R7S \
  -H "Authorization: Bearer bkz_live_abc123"

200 OK

{
  "data": {
    "id": "dlv_01JE7K8X2M3N4P5Q6R7S",
    "event": "deal.ready",
    "status": "delivered",
    "attempt_number": 1,
    "max_attempts": 5,
    "created_at": "2025-11-01T14:32:45Z",
    "delivered_at": "2025-11-01T14:32:45Z",
    "request": {
      "url": "https://yourapp.com/webhooks/banklyze",
      "headers": {
        "Content-Type": "application/json",
        "X-Banklyze-Event": "deal.ready",
        "X-Banklyze-Delivery": "dlv_01JE7K8X2M3N4P5Q6R7S",
        "X-Banklyze-Signature": "sha256=9f86d081884c7d659a2feaa0c55ad015..."
      },
      "body": {
        "event": "deal.ready",
        "deal_id": 42,
        "timestamp": "2025-11-01T14:32:45Z",
        "data": {
          "business_name": "Acme Trucking LLC",
          "health_score": 74.2,
          "grade": "B",
          "document_count": 3
        }
      }
    },
    "response": {
      "status_code": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "{\"received\": true}",
      "time_ms": 142
    }
  }
}

Bulk Ingest

CRM