Register a real-estate webhook subscription

POST 
/partner/webhook/subscription

Registers a destination and chooses which events it receives, optionally narrowed by outcome and by project. Self-service: no coordination with banca.me is needed.

This is the endpoint for real-estate partners — the ones consuming risk evaluations. It is the only route that can subscribe you to new_lead and pre_approve, the two events that follow a lead through the funnel: one when the lead is created, one when its evaluation finishes. Both require the evaluation module.

BNPL partners cannot use this endpoint

A partner whose product is BNPL is rejected here with 422 ERR_PARTNER_PRODUCT_CANNOT_RECEIVE_WEBHOOKS, whatever events the request asks for — there is no combination that gets through. BNPL integrations register through POST /partner/webhook instead.

The body is still parsed and the destination still validated first, so a malformed request from a BNPL partner comes back as ERR_MISSING_DATA or ERR_INVALID_DATA rather than the product rejection. Both are 422; only the error code differs.

Destinations created here verify by token — every delivery carries the bancame-webhook-secret header and no bancame-signature. That is fixed at creation and cannot be changed afterwards; see Verify the Webhook Token. For the payload, see the Event Catalog.

Creating versus reconciling

Posting a URL you have not registered creates it and returns 201 with the secret as a plain string. Posting a URL you already registered reconciles it — the subscriptions are updated to match the request and the response is 200 with the destination, without the secret. The secret is shown once, at creation, and cannot be retrieved later.

Reconciling never changes the verification scheme.

Limits

You may have 10 active destinations. Deleting one frees its slot immediately, so deleting and re-registering does not consume the quota.

Request

Responses

200

Existing destination reconciled. The secret is not included — it is only ever returned by the 201 that created the destination.

201

Destination created

401

Unauthorized - Invalid or missing API credentials

403

Forbidden. Either the partner is inactive, or ERR_PARTNER_DOES_NOT_HAVE_ACCESS_TO_MODULE: evaluation — pre_approve or new_lead was requested without the evaluation module. Both events require it. The message names the missing module.

409

Conflict (ERR_PARTNER_WEBHOOK_SCHEME_IS_NOT_TOKEN) - This URL is already registered as an HMAC destination, through the BNPL route POST /partner/webhook. Verification schemes are immutable, so it cannot be reconciled here. Register a different URL, or delete the existing destination first.

422

Unprocessable Entity. One of: ERR_MISSING_DATA (url absent or empty) · ERR_INVALID_DATA (not HTTPS or not publicly resolvable; empty or unknown eventTypes; filters or externalEntityId without eventTypes; filters on a subscription that does not include pre_approve; an unknown filter key or an empty/unknown results value) · ERR_TOO_MANY_PARTNER_WEBHOOKS (10 active destinations already) · ERR_PARTNER_PRODUCT_CANNOT_RECEIVE_WEBHOOKS (BNPL partner — this route is for real-estate partners; register through POST /partner/webhook instead)

429

Too Many Requests - Rate limit exceeded