Developer API / Rental webhooks for new Dutch listings

Rental webhooks for new Dutch listings

Let WoningMe call your server when a new listing matches one of your searches, instead of asking the API again and again.

Set one URL for your account

You configure a single webhook URL. Every new listing that matches any of your searches is sent to it. A listing that matches several searches is sent once, with all matching searches named in the message.

curl -X PUT https://woning.me/api/developer/v1/webhook \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://you.dev/hooks/woningme"}'

The response contains the signing secret. It is created the first time and kept when you change the URL.

What your server receives

POST /hooks/woningme
X-WoningMe-Signature: sha256=<hex digest>

{
  "event": "listing.new",
  "searches": [{"id": 42, "label": "Utrecht"}],
  "property": { "street": "Kerkstraat 12", "city": "Utrecht", ... }
}

The property object has the same shape as in the properties endpoint. Use the id values in searches to route the listing inside your own system. The X-WoningMe-Delivery header stays the same across a retry, so you can use it to ignore duplicates.

Verify the signature

The signature is an HMAC-SHA256 digest of the raw request body, keyed with your secret. Verify it before you trust a payload, and compare in constant time.

import hashlib, hmac

def verify(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Test, rotate and inspect

Endpoint	Purpose
`POST /api/developer/v1/webhook/test`	Send a signed `webhook.test` event and see whether your URL answered with a 2xx.
`POST /api/developer/v1/webhook/rotate-secret`	Create a new signing secret. Deliveries use it immediately.
`GET /api/developer/v1/webhook/deliveries`	Recent deliveries, newest first, with the searches they matched.

Retries

When your endpoint does not answer with a 2xx status or times out, WoningMe retries once after about 30 seconds and then gives up. Check the delivery history to see what happened. Webhook delivery stops when your subscription ends or a payment fails.

Webhooks or polling?

Polling is simple and fine for a dashboard that refreshes now and then. Webhooks fit alerts and monitoring, where you want a new listing the moment it matches without spending requests on empty answers. You can combine them: use a webhook to learn that something new exists and the properties endpoint to load more context.

The complete reference is in the webhook documentation.

Try it on a real search

Personal plan: €15/month for personal and non-commercial use, with a 2-day free trial. A payment method is required before the trial starts, and nothing is charged during the trial.

Start 2-day free trial Commercial use? Explore collaboration