# How do I get real-time property alerts for my filters delivered to a webhook?

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

Use New Market Leads on the Casafari REST API. Sign in with `POST /login`, create a feed with `POST /alerts-api/feeds` (`feed_name` and `filters`), then register your endpoint with `PUT /alerts-api/webhooks`. The feed follows the property graph and sends signed alerts for new properties, price rises and cuts, reservations, removals from the market and sales.

Products: [New Market Leads](/docs/alerts).

## Short answer

A New Market Leads feed follows the property graph for a set of filters. It emits an alert when a matching property appears, rises or drops in price, is reserved, is removed from the market or is sold.

You create the feed once and register a webhook. Casafari then sends each alert to your endpoint, signed with a secret you can rotate.

## Steps

### Get a token with `POST /login`

1. Call `POST https://api.casafari.com/login` with your account `email` and `password` as JSON. It returns `access_token` and `refresh_token` (JWT).
2. Send `Authorization: Bearer <access_token>` on every request. Renew the token with `GET /refresh-token` using the refresh token. If that answers `401`, log in again.

An integration or agent without a person uses an API client instead. The account owner creates it in Settings → API Clients on https://docs.api.casafari.com/. You exchange its `client_id` and `client_secret` at `POST https://api.casafari.com/oauth/token` with `grant_type=client_credentials`.

### Create the feed: `POST /alerts-api/feeds` with feed_name and filters

3. Send `feed_name` and `filters`. Only `business_type` is required inside `filters` (a key named `operation` is refused). Set the webhook first (`PUT /alerts-api/webhooks`): creating a feed before any webhook is set answers `409` with `No webhook configured`. The keys include `location_ids`, `types`, `statuses`, `alert_subtypes`, `price_range`, `bedrooms_range`, `private`, `bank`, `auction` and `new_development`. The full list is on the [Create feed](/docs/rest/alerts/create-feed) page.

### Set the delivery URL: `PUT /alerts-api/webhooks`

4. Send `url`. The operation takes a single `url` and no feed id: it sets the delivery URL for the account.

### Verify signatures; rotate with `POST /alerts-api/webhooks/rotate-secret` (24-hour grace unless immediate)

5. Check each delivery's signature with your signing secret before you trust it. The signature scheme is described on the [Set webhook URL](/docs/rest/alerts/set-webhook-url) and [Rotate signing secret](/docs/rest/alerts/rotate-signing-secret) pages, not in the sources of this page.
6. To rotate the secret, call `POST /alerts-api/webhooks/rotate-secret`. With `immediate` false (the default), the previous secrets keep working for a 24-hour grace window, which leaves time to update your verifier. Set `immediate` to true to skip the grace window.

### List, inspect and delete feeds: `GET /alerts-api/feeds`, `GET /alerts-api/feeds/{feed_id}`, `DELETE /alerts-api/feeds/{feed_id}`

7. `GET /alerts-api/feeds` lists your feeds. `GET /alerts-api/feeds/{feed_id}` returns one feed. `DELETE /alerts-api/feeds/{feed_id}` removes it.

### Polling alternative on v1: `GET /api/v1/listing-alerts/feeds/{id}`

8. Casafari client accounts can create a v1 feed with `POST /api/v1/listing-alerts/feeds` (`name`, `filter`).
9. They then read its alerts on demand with `GET /api/v1/listing-alerts/feeds/{id}` instead of receiving a webhook. See [Get alerts by feed (v1)](/docs/rest/alerts/get-alerts-by-feed-v1).

## Example: new 3-bedroom apartments under 400,000 in Lisbon

Create the feed with `POST /alerts-api/feeds`:

```json
{
  "feed_name": "Lisbon 3-bed apartments under 400000",
  "filters": { "business_type": "sale" }
}
```

With the webhook already set, add to `filters` the Lisbon location id in `location_ids`, the apartment type in `types`, `alert_subtypes` `["new"]`, 3 bedrooms in `bedrooms_range` and a maximum price in `price_range`. The accepted values are on the [Create feed](/docs/rest/alerts/create-feed) page.

The delivery URL, set beforehand with `PUT /alerts-api/webhooks`:

```json
{ "url": "https://example.com/casafari/alerts" }
```

The fields of a delivered alert are documented on the [Alert](/docs/data-export/alert) entity page. This page does not reproduce a sample delivery.

A Casafari client account can run the same filter on demand with `POST /api/v1/listing-alerts/search`. Replace `<LISBON_LOCATION_ID>` with the location id:

```json
{
  "operation": "sale",
  "location_ids": [<LISBON_LOCATION_ID>],
  "types": ["apartment"],
  "bedrooms_from": 3,
  "bedrooms_to": 3,
  "price_to": 400000,
  "alert_date_from": "2026-10-01"
}
```

Asking an assistant on the Casafari MCP server to set up these alerts will not work, because alerts are not offered over MCP. An agent holding REST credentials, such as an API client, can make these calls itself.

## How to read the result

### One alert per property event

The property graph merges every advertisement of a property into one record. An alert is about an event on that property, not on one advertisement of it. A home advertised by several agencies produces one alert per event, not one per agency.

### Alert kinds and when each fires

- **New property**: a property matching your filters appears in the graph.
- **Price rise or price cut**: the property's price changes. Every change is recorded with its date in `sale_price_history` or `rent_price_history`.
- **Reservation**: the property's status becomes reserved.
- **Removal from the market**: the property stops being advertised.
- **Sale**: the status becomes sold (rented, for rentals).

In a feed's `filters`, `alert_subtypes` takes `new`, `price_increased`, `price_decreased`, `reserved`, `delisted` and `sold`. Use new properties and price cuts for prospecting, and reservations and sales to close out leads in your CRM.

## Limits

### REST only

The `/alerts-api/*` feed and webhook operations are available to Casafari clients with their Casafari account; self-serve access for new users is coming soon. You sign in with `POST /login` or an API client. The `/api/v1/listing-alerts/*` operations are for Casafari client accounts. Alerts are not offered over MCP.

### One webhook URL per account as exposed by `PUT /alerts-api/webhooks`

`PUT /alerts-api/webhooks` takes one `url` and no feed id. To route feeds to different systems, fan the deliveries out from your own endpoint.

### No delivery figures are published here

The sources publish no prices, quotas, delivery timing, retry policy, refresh frequency or SLA. For those, ask [Casafari](https://www.casafari.com/).

## Questions

### How do I verify a webhook signature?

Deliveries are signed with a secret tied to your account, and you check each signature before trusting the payload. The header name and algorithm are described on the Set webhook URL and Rotate signing secret operation pages, not in the sources of this page. When rotating with `POST /alerts-api/webhooks/rotate-secret`, the default keeps previous secrets valid for a 24-hour grace window.

### What happens if my endpoint is down?

The sources do not describe retry behaviour, so this page cannot say whether missed deliveries are resent. Casafari client accounts can read a v1 feed's alerts on demand with `GET /api/v1/listing-alerts/feeds/{id}` to fill gaps, or query `POST /api/v1/listing-alerts/search` by date. For delivery guarantees, ask Casafari at https://www.casafari.com/.

### Can I have several feeds with different filters?

Yes. Each `POST /alerts-api/feeds` call creates a feed with its own `feed_name` and `filters`. `GET /alerts-api/feeds` lists them all, and `DELETE /alerts-api/feeds/{feed_id}` removes one. `PUT /alerts-api/webhooks` sets a single `url` for the account, so split deliveries by feed in your own endpoint. The sources publish no limit on the number of feeds.

### Can an AI assistant read my alerts?

Not through the Casafari MCP server: New Market Leads is offered over the REST API only, so no MCP tool returns alerts. Your own agent or application can receive the webhook, or read alerts over REST, and then pass them to an assistant. An agent running without a person signs in to the REST API with an API client and the client credentials grant.

### How is a feed updated: v1 PUT or recreate?

On v1, Casafari client accounts update a feed in place with `PUT /api/v1/listing-alerts/feeds/{id}/update`, sending `name` and `filter`. The `/alerts-api` operations documented on the hub have create, get, list and delete but no update, so delete the feed and create a new one.

All use cases: [Use cases](/docs/use-cases#leads).