Webhooks Config

Configure a webhook endpoint to receive real-time event notifications from Banklyze. Each organization has a single webhook configuration consisting of a target URL, a list of subscribed event types, and an optional HMAC-SHA256 signing secret used to verify delivery authenticity.

For documentation on the webhook payload structure and all available event types, see the Webhooks guide. This page covers only the configuration API endpoints.

Retrieve the current webhook configuration for your organization. Returns 404 Not Found if no webhook configuration has been set up yet. The signing secret is never returned — it is write-only.

Example

curl

curl -X GET https://api.banklyze.com/v1/webhooks/config \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "url": "https://your-app.com/webhooks/banklyze",
  "events": [
    "deal.ready",
    "deal.decision_set",
    "document.processing_complete",
    "document.processing_failed"
  ],
  "active": true,
  "created_at": "2026-01-10T09:00:00Z",
  "updated_at": "2026-02-01T14:30:00Z"
}

Create or fully replace the webhook configuration for your organization. This is an upsert — if a configuration already exists it is overwritten. All fields in the request body are applied atomically. Omitting secret removes any previously configured signing secret.

The url must be an HTTPS endpoint reachable from the internet. HTTP endpoints are rejected. Banklyze delivers webhooks with a 10-second timeout and retries up to 3 times with exponential backoff on non-2xx responses.

Request Body

Name	Type	Required	Description
url	string	Required	HTTPS URL of the endpoint that will receive webhook deliveries
events	string[]	Required	Array of event type strings to subscribe to. An empty array disables all delivery without removing the config. See the Webhooks guide for the full list of event types.
secret	string	Optional	Optional signing secret used to compute the HMAC-SHA256 signature in the X-Banklyze-Signature header. Must be between 16 and 256 characters. Write-only — never returned by the API.

Example

curl

curl -X PUT https://api.banklyze.com/v1/webhooks/config \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/banklyze",
    "events": [
      "deal.ready",
      "deal.decision_set",
      "document.processing_complete",
      "document.processing_failed"
    ],
    "secret": "whsec_your_signing_secret_here"
  }'

Response

Response — 200 OK

{
  "url": "https://your-app.com/webhooks/banklyze",
  "events": [
    "deal.ready",
    "deal.decision_set",
    "document.processing_complete",
    "document.processing_failed"
  ],
  "active": true,
  "created_at": "2026-01-10T09:00:00Z",
  "updated_at": "2026-03-04T11:15:00Z"
}

Remove the webhook configuration for your organization. After deletion, no further webhook deliveries will be attempted. Any in-flight deliveries already queued before deletion will still be attempted. This action is reversible — a new configuration can be created at any time with PUT /webhooks/config.

Example

curl

curl -X DELETE https://api.banklyze.com/v1/webhooks/config \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "status": "ok",
  "message": "Webhook configuration removed"
}

Send a synthetic webhook.test event to the currently configured webhook URL. Use this to verify your endpoint is reachable and your signature verification logic is working correctly before going live. The test payload is delivered synchronously — the response includes the HTTP status code your endpoint returned and the round-trip duration.

Returns 404 Not Found if no webhook configuration exists. If your endpoint returns a non-2xx status, the response will reflect that but will not trigger the automatic retry logic.

Example

curl

curl -X POST https://api.banklyze.com/v1/webhooks/test \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "delivery_status": "delivered",
  "response_code": 200,
  "url": "https://your-app.com/webhooks/banklyze",
  "event": "webhook.test",
  "delivered_at": "2026-03-04T11:20:05Z",
  "duration_ms": 143
}