Webhooks
Get notified when a site leaves measurement or is verified, instead of polling.
A site is measured in the background. Instead of polling Get a site or List sites, register a URL and Duranta sends an HTTPS POST when a site reaches a final status or a person verifies it.
Polling still works
Webhooks are a shortcut, not the only path. If your receiver was down or an endpoint was disabled, call ListSites to catch up on statuses and results.
Events
| Type | Sent when |
|---|---|
WEBHOOK_EVENT_TYPE_SITE_STATUS_CHANGE | A site reaches SITE_STATUS_COMPLETED, SITE_STATUS_FAILED or SITE_STATUS_ISSUE. data.site.status is the new status, and data.site.error says why for the last two. |
WEBHOOK_EVENT_TYPE_SITE_VERIFIED | A person checked a completed site in the Duranta app, corrected its surfaces if needed, and marked it verified. Saving changed surfaces clears the mark, so a site corrected later is sent again once it is verified again. |
WEBHOOK_EVENT_TYPE_TEST | You call SendTestEvent to check your receiver and signature check. Carries a sample site. |
An event is sent on each change of status, so a site that is scanned again sends a new event when it finishes again. Every endpoint receives every site event. WEBHOOK_EVENT_TYPE_TEST goes only to the endpoint you test. New event types may be added later, so ignore a type you do not handle and still answer 2xx.
Payload
{
"id": "evt_9f2c4a6e1b7d4c3a8e5f0a1b2c3d4e5f",
"type": "WEBHOOK_EVENT_TYPE_SITE_STATUS_CHANGE",
"timestamp": "2026-10-30T14:05:12Z",
"data": {
"site": {
"externalId": "PROP-000001",
"address": {
"line1": "2910 Mall Dr",
"city": "Eau Claire",
"region": "WI",
"postalCode": "54701",
"country": "US"
},
"status": "SITE_STATUS_COMPLETED",
"appUrl": "https://app.getduranta.com/a/t000000123a/scanner/projects/LrksiDbMOti/sites/wxq2h3OXkGi",
"location": { "latitude": 44.788607, "longitude": -91.462058 },
"parcelAreaSqFt": 92422.95,
"surfaces": [
{ "type": "SURFACE_TYPE_LAWN", "areaSqFt": 35567.2, "perimeterFt": 3101.32, "segmentCount": 7, "areaExclTreesSqFt": 31204.85 },
{ "type": "SURFACE_TYPE_BEDS", "areaSqFt": 3006.12, "perimeterFt": 941.39, "segmentCount": 13 }
],
"submittedAt": "2026-10-30T14:03:40Z",
"tier": "RESULT_TIER_IMAGE_AND_SEGMENTS",
"aiModel": "AI_MODEL_COMMERCIAL_FAST",
"propertyBoundary": "PROPERTY_BOUNDARY_OFFICIAL",
"updatedAt": "2026-10-30T14:05:11Z",
"revision": "3"
}
}
}data.site is the same Site that ListSites returns, as of the event, without the geometry and the image. The Site has no verified field: the WEBHOOK_EVENT_TYPE_SITE_VERIFIED event is the only signal that a site was verified. Compare revision or updatedAt with what you stored, and call GetSite for the latest state or for the geometry and image.
Manage endpoints
Create, list and delete endpoints with the Webhooks reference methods (they need the sites:scan scope), or in the Duranta app under Settings → API.
- The URL must be
https, without a username or password, and resolve to a public address. - A workspace can have up to 10 endpoints.
- The signing secret (
whsec_...) is shown once, when you create the endpoint. Store it then.
Verify the signature
Anyone can post to your URL, so check every request. Each one carries Standard Webhooks headers:
| Header | Value |
|---|---|
webhook-id | The event id. The same on every retry. |
webhook-timestamp | Unix time in seconds when the attempt was sent. |
webhook-signature | v1,<base64>: HMAC-SHA256 of id.timestamp.body. |
We recommend the official standardwebhooks libraries. Pass them the raw request body, not re-serialized JSON, and the secret as it was shown, including whsec_.
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.WEBHOOK_SECRET);
// Express: use express.raw({ type: 'application/json' }) so req.body is the raw body.
app.post('/duranta-webhook', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = wh.verify(req.body, req.headers); // throws on a bad signature or an old timestamp
} catch {
return res.sendStatus(400);
}
// Store event.id, then process event.data.site.
res.sendStatus(200);
});To verify without a library, follow the Standard Webhooks spec.
Delivery
- Answer with a
2xxstatus within 15 seconds. Do the real work after you respond. - Redirects are not followed. A
3xxcounts as a failure. - Delivery is at least once and not ordered. Ignore an event whose
webhook-idyou already handled. - Any other answer, a timeout or a connection error is retried, up to 8 attempts over about 27 hours.
- A
410 Goneanswer disables the endpoint immediately. Create a new endpoint to receive events again. - An endpoint that has failed continuously for more than 5 days is disabled too.
disabledAtanddisabledReason(goneorfailing) show it in the list. - Deliveries are kept for 30 days. List deliveries shows each event's status, number of attempts, last HTTP status and error. Duranta does not keep your response body.