parcel.permit_filed — a permit was filed (or first observed) for a tracked parcel

PropRaven POSTs this event when a new permit is matched to a parcel matching one of your webhook filters. Fires once per permit per parcel; duplicate filings from the same jurisdiction de-dupe via permit_id. Signature verification: HMAC-SHA256 over <unix_ms>.<raw_body>, secret from webhook creation, header X-PropRaven-Signature: t=<unix_ms>,v1=<sig>. Reject if the request timestamp is more than 5 minutes from now.

postWebhookparcel.permit_filed

Headers

X-PropRaven-Signaturestring required

t=<unix_ms>,v1=<hex>: HMAC-SHA256 of <t>.<raw_body> keyed with the endpoint secret. Reject if the timestamp is more than 5 minutes from now.

X-PropRaven-Event-Idstring required

The payload's event_id (the same on every retry).

X-PropRaven-Event-Typestring required

The payload's event_type.

X-PropRaven-Delivery-Idstring required

The delivery id shown by GET /webhooks/{id}/deliveries (the same on every retry).

X-PropRaven-Attemptstring required

Attempt number, starting at 1 (equals the payload's delivery_attempt).

Payload

event_type'parcel.permit_filed' required
event_idstring required

Deterministic (sha256 of source, record id and event type). A retry re-sends the same event_id: de-duplicate on it.

occurred_atstring date-time required

The record's own date when it has one, else the time PropRaven ingested it; see occurred_at_basis.

occurred_at_basis'filed_date' | 'issued_date' | 'curated_at' required

Which column dated the event.

delivery_attemptinteger required

Starts at 1; increments on every retry (equals the X-PropRaven-Attempt header).

parcel_idstring required

The county assessor's parcel number the record was matched to (e.g. 12104406). County-scoped, NOT unique nationally and not county:parcel: identify the parcel with state_fips + county_fips + parcel_id, or with canonical_id.

state_fipsstring nullable required

2-digit state FIPS of the record; null when the publisher gave none.

county_fipsstring nullable required

3-digit county FIPS of the record as published (a 5-digit value is cut to its last 3); null when absent. Placeholders such as 000 are passed through, not repaired.

canonical_idstring

Parcel-scoped endpoints only: the watched parcel this event matched, state_fips:county_fips:parcel_id. Absent on state/county endpoints.

match_basis'state_county_parcel_id' | 'state_unique_parcel_id' | 'null' nullable

Parcel-scoped endpoints only (with canonical_id): state_county_parcel_id = the record's own county matched; state_unique_parcel_id = the record's county was unknown and the parcel number is unique in the state.

permit_idstring required

PropRaven internal permit id (stable across re-ingests).

permit_numberstring nullable

Jurisdiction-issued permit number.

permit_typestring nullable

Building, electrical, roofing, demolition, etc.

permit_statusstring nullable

Filed, issued, in_review, final, expired, withdrawn.

filed_datestring date nullable
issued_datestring date nullable
descriptionstring nullable
estimated_costnumber nullable

Declared job cost in USD.

contractor_namestring nullable
contractor_licensestring nullable
applicant_namestring nullable
jurisdiction_idstring nullable

PropRaven jurisdiction id; join to /v1/jurisdictions.

source_run_idstring nullable

Reserved for the PropRaven ingest run; null today.

Response

Any 2xx status acks the delivery; the body is not read. A non-2xx response is retried up to 8 attempts in all (waits of 1 min, 5 min, 15 min, 30 min, 1 h, 2 h and 6 h), then the delivery is dead_lettered. A send whose outcome is unknown (network error or timeout) stays in_flight and is not retried automatically.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.