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 and pre_approve
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 and pre_approve — the lead being created, and its evaluation finishing. Both 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 all API requests is:

https://api.banca.me

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

Error Handling

The API uses standard HTTP status codes and provides detailed error messages in the response body. Common error codes include:

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

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 200 OK within 5 seconds)
• Process webhook data asynchronously after acknowledging receipt
• Verify webhook signatures for security

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 webhook signatures using your shared secret
• 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