Version: 1.0.0

Webhooks API

The banca.me webhooks API lets partners register endpoints that banca.me calls when something happens, instead of polling for it.

There are two integrations, and you use exactly one

Which registration endpoint you use is decided by your product, not by preference. They are not two ways of doing the same thing — each one rejects or ignores what belongs to the other.

	BNPL	Real estate
Register with	POST /partner/webhook	POST /partner/webhook/subscription
Events you receive	loan_approved	new_lead, pre_approve and reevaluation
Verification	HMAC — bancame-signature	Token — bancame-webhook-secret
Choose events, filters, project scope	No — fixed to loan_approved	Yes
If you call the other one	it ignores the extra fields and registers a plain loan_approved destination	rejected, 422 ERR_PARTNER_PRODUCT_CANNOT_RECEIVE_WEBHOOKS

BNPL partners: POST /partner/webhook is your route, including for a new integration. It is not deprecated — the subscription endpoint refuses BNPL partners outright.

Real-estate partners: POST /partner/webhook/subscription is your route. It is the only one that can subscribe you to new_lead, pre_approve and reevaluation — the lead being created, its evaluation finishing, and a re-evaluation of it finishing. All three require the evaluation module.

Listing and deleting destinations is shared: both integrations use GET /partner/webhook and DELETE /partner/webhook/{id}.

Features

• Register and manage webhook destinations, up to 10 active at a time
• Receive real-time event notifications
• Verified delivery — HMAC or token, decided by the endpoint you registered through
• Automatic retry for failed deliveries, carrying the same eventId — but the budget is per event: new_lead gets a single attempt with a 3-second timeout and is never retried

Base URL

The base URL for production API requests is:

https://api.banca.me

For integration and testing use https://beta.api.banca.me (development) or https://automation.api.banca.me (automation). See Environments.

Rate Limiting

The API implements rate limiting to ensure fair usage:

• 2 requests per second, measured over a one-second window — it is a burst limit, not a per-minute quota, so three calls inside the same second return 429 even if the minute is nearly idle. Space out bulk operations rather than batching them.
• 429 status code is returned when limits are exceeded, with the text body You have reached maximum retries in this timespan. rather than JSON

Error Handling

The API uses standard HTTP status codes. Common error codes include:

• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 409: Conflict
• 422: Invalid data
• 429: Too Many Requests
• 500: Internal Server Error

Errors other than 429 return a JSON body like this one:

{
  "data": {
    "status": 422,
    "url": "/partner/webhook/subscription",
    "ip": "203.0.113.10",
    "message": "ERR_INVALID_DATA"
  }
}

message carries the error code on 422 responses. Other 4xx responses leave it out and carry only the status, so tell those cases apart by status code — each endpoint lists what its statuses mean.

Data formats

The API accepts and returns data in the following formats:

• Request: application/json
• Response: application/json

Best practices

1. Event Handling:

• Implement idempotent webhook processing to handle potential duplicate deliveries
• Acknowledge webhook receipt promptly (respond with any 2xx within 3 seconds — new_lead times out after 3 seconds, the other events after 5)
• Process webhook data asynchronously after acknowledging receipt
• Verify every delivery — by HMAC signature or by token, depending on the destination

2. Endpoint Configuration:

• Use HTTPS endpoints with valid certificates
• Implement proper error handling
• Set up monitoring for webhook failures
• Ensure your endpoint is reliable and accessible

3. Security:

• Verify each delivery with the secret you received at registration
• Store webhook credentials securely
• Validate payload formats and event types
• Implement rate limiting on your webhook endpoint

Authentication

HTTP: Bearer Auth

Partner access token provided by banca.me

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer