Planning webhooks
Planning webhooks: delivery and recovery.
Keep a local planning-data view current with signed events and a recoverable event stream. Verify delivery, store each event safely, and reconcile after receiver downtime.
Developers use PlanWire when they need live planning data without maintaining council-source integrations, with UPRN where available for property-dataset joins. Source-linked application records, freshness metadata and webhook workflows. Check current council-level coverage and history for your integration.
Recover recorded events
Replace WEBHOOK_ID with the id returned at registration. Use your last fully persisted recovery cursor instead of 0 after the initial read.
curl "https://api.planwire.io/v1/webhooks/WEBHOOK_ID/events?after=0&limit=500" \ -H "X-API-Key: YOUR_API_KEY"
From a signed delivery to a durable local record
Start with one council or postcode prefix. Developer includes one scoped webhook; broader national coverage requires Production or above. Free sample keys cannot register webhooks.
1. Register a scoped receiver
POST /v1/webhooks with a public HTTPS URL and filters.councilId or filters.postcodePrefix. Optional status and applicationType filters narrow matching records. Store the returned secret server-side.
2. Verify and persist
Verify X-PlanWire-Signature against the unmodified request body with HMAC-SHA256 and a constant-time comparison. Persist the event before acknowledging it; deduplicate repeated deliveries by event id.
3. Recover in cursor order
Read GET /v1/webhooks/:id/events?after=0&limit=500. Persist the complete page before saving meta.nextCursor; continue while meta.hasMore is true. Do not advance recovery progress from an out-of-order webhook delivery.
4. Keep provenance and limits
Apply captured payloads idempotently and retain council references and source evidence. A current-record lookup is not event replay. Unknown or stale source data must remain distinguishable from an available API.
Delivery, recovery and current state are different
| Live delivery | application.new means newly observed by PlanWire, not necessarily newly submitted to a council. application.updated can include captured document-only changes. |
|---|---|
| Retry window | Failed durable deliveries retry with increasing delays for up to 24 hours. Worker or source outages can delay delivery; this is not a promise of immediate council publication. |
| Recovery history | Captured events are retained for at least 30 days while the subscription remains. The stream cannot recreate changes from before durable capture began. Deleting the webhook deletes its recovery stream. |
| Current-record lookup | Fetch the latest stored application separately when you need its present state. The missed-delivery endpoint is an attempt log, not the ordered recovery stream. |
| Usage | Recovery API calls consume request allowance. Webhook deliveries do not. Confirm your plan and source coverage before increasing scope. |
Questions buyers ask
Can I test without a customer integration?
Yes. Run the PlanWire-owned receiver/cache example and its synthetic duplicate, signature and recovery tests. It is reference code, not a customer case study or production-performance benchmark.
Does a planning event prove construction has started?
No. It records planning activity observed by PlanWire. A planning decision is not a confirmed construction start, order or materials requirement.
Can I use radius or keyword filters on a webhook?
Do not assume REST search filters also apply to webhook registration. The documented webhook filters are councilId, postcodePrefix, status and applicationType; implement additional selection in your own receiver where appropriate.
Related acquisition pages