Skip to main content

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 the events that follow a lead through the funnel: new_lead when the lead is created, pre_approve when its evaluation finishes, and reevaluation when you re-evaluate it. All three require the evaluation module.

Mortgage lenders also register installment_paid here: one delivery for each installment of their loans that banca.me collects. It needs no module and takes no filters. Any other partner that asks for it gets 422 ERR_PARTNER_EVENT_TYPE_NOT_AVAILABLE_FOR_PRODUCT. See installment_paid.

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.

Always send eventTypes when creating

A new URL registered without eventTypes is subscribed to loan_approved alone — the BNPL event, which real-estate partners do not receive. Name the events you want.

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 and returns 200 with the destination, without the secret. The secret is shown once, at creation, and cannot be retrieved later.

Reconciling:

  • With eventTypes, replaces the destination's subscriptions with exactly what the request carries. filters and externalEntityId left out of that request are cleared.
  • Without eventTypes, leaves the subscriptions, filters and scope as they are.
  • Reactivates the destination if you had deleted it, with its original token — it is not a way to get a new one. A reactivated destination takes one of your 10 slots again.
  • Never changes the verification scheme.

Limits​

You may have 10 active destinations. Deleting one frees its slot immediately.

Request​

Responses​

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