Webhooks

When something changes on your account — an action item gets filed, a visit completes, evidence gets attached — SiteVisit can POST a signed JSON payload to a URL you control. Use it to keep a work-order system in sync, post notifications to Slack, feed a data warehouse, or fan out into any other downstream system. Webhooks share authentication style with Stripe, so any code you’ve written to verify a Stripe webhook ports over with a one-line constant swap.

Setting up an endpoint

Two ways: From the dashboard — open Settings → Developers → Webhooks, click Add endpoint, paste your URL, pick the events to subscribe to (or “all”), and save. We’ll display the signing secret once — copy it now, store it in your secret manager. Via the API — issue a key in Settings → Developers, then:

curl -X POST https://sitevisit.app/api/v1/webhook-endpoints \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production work-order sync",
    "url": "https://your-server.com/webhooks/sitevisit",
    "events": ["action_item.created", "action_item.completed", "site_visit.ready"]
  }'

The response includes a signingSecret field — save it now. We hash nothing here (we need the raw secret on every send to sign), but the value is never returned again after creation. Rotate by deleting + recreating the endpoint. Pass "events": [] to subscribe to everything (recommended for first integration — you can ignore events you don’t care about on your side).

Event catalog

17 event types across four domains:

Event	When
`property.created`	New property added
`property.updated`	Name / address / notes / icon edited
`property.deleted`	Property removed (cascades downstream)
`site_visit.created`	New visit filed
`site_visit.updated`	Title / visit date / summary / notes edited
`site_visit.processing`	Video upload begins processing
`site_visit.ready`	AI extraction complete, report ready
`site_visit.sent`	Report emailed to recipients
`site_visit.completed`	Visit marked done (explicitly OR implicitly via send)
`site_visit.deleted`	Visit removed
`action_item.created`	New item filed (AI extraction OR manual)
`action_item.updated`	Title / priority / location / category / description changed
`action_item.assigned`	Assignee specifically changed (fires alongside `updated`)
`action_item.completed`	Marked DONE with attribution
`action_item.reopened`	DONE → OPEN / IN_PROGRESS
`action_item.deleted`	Item removed
`evidence.attached`	Photo / video attached to an action item

Payload envelope

Every webhook delivery has the same outer shape:

{
  "id": "evt_abc123def456",
  "event_type": "action_item.created",
  "livemode": true,
  "created_at": "2026-06-06T15:32:11.789Z",
  "data": {
    "action_item": {
      "id": "cmq1l7sf50009kv04tv2cgm4x",
      "title": "Replace bulb at front entrance",
      "...": "...full ActionItemDto"
    }
  }
}

id is unique per event. Dedupe on this in your handler — we may deliver the same event more than once if your endpoint returns a non-2xx and we retry.
event_type is stable across versions. Branch your logic on this string.
livemode is true for events triggered by sv_live_* keys (real customer data) and false for events triggered by sv_test_* keys (sandbox dataset). Same Stripe convention; lets you ignore test traffic in production pipelines without parsing the resource itself.
created_at is the time the event was emitted (UTC ISO-8601). Different from any timestamps inside data.
data contains the relevant resource(s). Always a JSON object, shape depends on event type. See Event payload reference below.

Test mode

Webhook endpoints have a mode of either live or test, set when you create the endpoint in Settings → Developers → Webhooks. The mode determines which traffic the endpoint receives:

Live endpoints only receive events from sv_live_* API keys, the dashboard, and OAuth flows. livemode: true on every payload.
Test endpoints only receive events from sv_test_* keys. livemode: false on every payload.

The streams never cross — test traffic never fires a live endpoint, and vice versa. Same Stripe model: develop your integration against a test endpoint while you build, swap to a live endpoint when you ship. When you create an endpoint via the API, pass "mode": "test" to make it a test endpoint (defaults to "live" when omitted):

curl -X POST https://sitevisit.app/api/v1/webhook-endpoints \
  -H "Authorization: Bearer sv_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "local dev — ngrok tunnel",
    "url": "https://abc123.ngrok-free.app/webhooks/sitevisit",
    "mode": "test",
    "events": []
  }'

Event payload reference

Every event’s data object shape, with realistic example values. DTO field names match what the v1 REST API returns — see the API reference for the full schema with descriptions per field.

Property events

`property.created`

{
  "id": "evt_p1...",
  "event_type": "property.created",
  "livemode": true,
  "created_at": "2026-06-07T09:14:22.103Z",
  "data": {
    "property": {
      "id": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "name": "Sunset Vista Apartments",
      "address": "742 Evergreen Terrace, Springfield",
      "notes": null,
      "iconEmoji": "🏢",
      "coverImageUrl": null,
      "isSample": false,
      "isTest": false,
      "createdAt": "2026-06-07T09:14:22.001Z",
      "updatedAt": "2026-06-07T09:14:22.001Z",
      "visitCount": 0,
      "openItemCount": 0
    }
  }
}

`property.updated`

Fires on any patch of name, address, notes, or iconEmoji. Payload is the full updated property (not a diff) — so a single handler can refresh your local cache without tracking what changed.

{
  "id": "evt_p2...",
  "event_type": "property.updated",
  "livemode": true,
  "created_at": "2026-06-07T11:02:18.503Z",
  "data": {
    "property": {
      "id": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "name": "Sunset Vista (Building A)",
      "address": "742 Evergreen Terrace, Springfield",
      "notes": "Newer of the two buildings; AC retrofitted 2024",
      "iconEmoji": "🏢",
      "coverImageUrl": "https://files.sitevisit.app/...",
      "isSample": false,
      "isTest": false,
      "createdAt": "2026-06-07T09:14:22.001Z",
      "updatedAt": "2026-06-07T11:02:18.412Z",
      "visitCount": 3,
      "openItemCount": 7
    }
  }
}

`property.deleted`

Cascade: deleting a property deletes all its site visits + action items + evidence. We don’t include the full property in this payload (it’s already gone from our DB by the time we send) — just the id.

{
  "id": "evt_p3...",
  "event_type": "property.deleted",
  "livemode": true,
  "created_at": "2026-06-07T14:55:09.722Z",
  "data": {
    "property_id": "cmp1aB2c3D4e5F6g7H8i9J0k1"
  }
}

Site visit events

`site_visit.created`

{
  "id": "evt_v1...",
  "event_type": "site_visit.created",
  "livemode": true,
  "created_at": "2026-06-07T08:30:00.044Z",
  "data": {
    "site_visit": {
      "id": "cmv1aB2c3D4e5F6g7H8i9J0k1",
      "propertyId": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "propertyName": "Sunset Vista Apartments",
      "title": "Q2 maintenance walkthrough",
      "status": "DRAFT",
      "visitDate": "2026-06-07T08:30:00.000Z",
      "summary": null,
      "notes": null,
      "recipients": [],
      "sentAt": null,
      "completedAt": null,
      "isTest": false,
      "createdAt": "2026-06-07T08:30:00.001Z",
      "updatedAt": "2026-06-07T08:30:00.001Z",
      "actionItemCount": 0,
      "openActionItemCount": 0,
      "publicReportUrl": "https://sitevisit.app/r/cmv1aB2c3D4e5F6g7H8i9J0k1"
    }
  }
}

`site_visit.updated`

Fires on any patch of title, visitDate, summary, or notes. Status transitions (DRAFT → PROCESSING → READY → SENT → DONE) fire their own dedicated events instead and are not emitted as updated.

{
  "id": "evt_v2...",
  "event_type": "site_visit.updated",
  "livemode": true,
  "created_at": "2026-06-07T08:45:11.122Z",
  "data": {
    "site_visit": { /* same shape as site_visit.created above */ }
  }
}

`site_visit.processing`

The video upload pipeline started transcoding + transcribing. No additional fields beyond the visit DTO.

{
  "id": "evt_v3...",
  "event_type": "site_visit.processing",
  "livemode": true,
  "created_at": "2026-06-07T08:46:02.788Z",
  "data": {
    "site_visit": { /* status: "PROCESSING" */ }
  }
}

`site_visit.ready`

The AI extraction finished — transcript, summary, and action items are all available. This is the event to subscribe to if you want to fan visits into a work-order system once they’re truly actionable.

{
  "id": "evt_v4...",
  "event_type": "site_visit.ready",
  "livemode": true,
  "created_at": "2026-06-07T08:51:34.901Z",
  "data": {
    "site_visit": { /* status: "READY", summary populated, actionItemCount > 0 */ }
  }
}

`site_visit.sent`

The asset manager hit the Email report button. recipients is the list of email addresses the report went to; sentAt is when.

{
  "id": "evt_v5...",
  "event_type": "site_visit.sent",
  "livemode": true,
  "created_at": "2026-06-07T09:15:22.011Z",
  "data": {
    "site_visit": {
      "id": "cmv1aB2c3D4e5F6g7H8i9J0k1",
      "title": "Q2 maintenance walkthrough",
      "property_id": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "sent_at": "2026-06-07T09:15:21.998Z",
      "recipients": ["maintenance@happyco.com", "ops@example.com"]
    }
  }
}

`site_visit.completed`

Fires on the transition to completed only — won’t re-fire on subsequent edits of an already-completed visit. Sending a report implicitly completes the visit, so this fires alongside site_visit.sent for the first send.

{
  "id": "evt_v6...",
  "event_type": "site_visit.completed",
  "livemode": true,
  "created_at": "2026-06-07T09:15:22.245Z",
  "data": {
    "site_visit": {
      "id": "cmv1aB2c3D4e5F6g7H8i9J0k1",
      "title": "Q2 maintenance walkthrough",
      "property_id": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "sent_at": "2026-06-07T09:15:21.998Z",
      "completed_at": "2026-06-07T09:15:21.998Z",
      "recipients": ["maintenance@happyco.com", "ops@example.com"]
    }
  }
}

`site_visit.deleted`

{
  "id": "evt_v7...",
  "event_type": "site_visit.deleted",
  "livemode": true,
  "created_at": "2026-06-07T10:00:00.000Z",
  "data": {
    "site_visit_id": "cmv1aB2c3D4e5F6g7H8i9J0k1"
  }
}

Action item events

`action_item.created`

Fires for both AI-extracted items (from the video transcription pipeline) and manually-filed items (via REST / MCP / dashboard).

{
  "id": "evt_a1...",
  "event_type": "action_item.created",
  "livemode": true,
  "created_at": "2026-06-07T08:51:36.124Z",
  "data": {
    "action_item": {
      "id": "cai1aB2c3D4e5F6g7H8i9J0k1",
      "siteVisitId": "cmv1aB2c3D4e5F6g7H8i9J0k1",
      "propertyId": "cmp1aB2c3D4e5F6g7H8i9J0k1",
      "propertyName": "Sunset Vista Apartments",
      "title": "Loose handrail on 2nd-floor landing",
      "description": "Wobbles ~2cm when grabbed; bolts need re-tightening",
      "category": "Safety",
      "location": "Building A, stairwell 2",
      "priority": "HIGH",
      "status": "OPEN",
      "assignee": null,
      "timestampSec": 154,
      "transcriptQuote": "...this rail is loose, you can feel it move when you grab it...",
      "completedAt": null,
      "completedBy": null,
      "completionNote": null,
      "completionPhotoUrl": null,
      "evidenceImageUrls": [
        "https://files.sitevisit.app/...",
        "https://files.sitevisit.app/..."
      ],
      "isTest": false,
      "order": 0,
      "createdAt": "2026-06-07T08:51:36.001Z",
      "updatedAt": "2026-06-07T08:51:36.001Z"
    }
  }
}

`action_item.updated`

Fires on any patch of title, description, category, location, priority, status, or assignee. Always fires when one of those fields changes — the more specific events below (assigned, completed, reopened) fire in addition, not instead.

{
  "id": "evt_a2...",
  "event_type": "action_item.updated",
  "livemode": true,
  "created_at": "2026-06-07T10:30:00.000Z",
  "data": {
    "action_item": { /* same shape as action_item.created */ }
  }
}

`action_item.assigned`

Fires when the assignee field changes (including being set for the first time or cleared back to null). Includes the previous assignee value for audit trails.

{
  "id": "evt_a3...",
  "event_type": "action_item.assigned",
  "livemode": true,
  "created_at": "2026-06-07T10:30:00.122Z",
  "data": {
    "action_item": { /* full DTO, assignee field updated */ },
    "previous_assignee": null
  }
}

`action_item.completed`

Fires when an item transitions to status: "DONE" via the POST /action-items/{id}/complete endpoint (the path that captures attribution + completion note + photo). A plain PATCH to status: "DONE" will fire action_item.updated but not action_item.completed — use the dedicated complete endpoint when you want the attribution trail.

{
  "id": "evt_a4...",
  "event_type": "action_item.completed",
  "livemode": true,
  "created_at": "2026-06-07T14:22:01.555Z",
  "data": {
    "action_item": {
      "id": "cai1aB2c3D4e5F6g7H8i9J0k1",
      "title": "Loose handrail on 2nd-floor landing",
      "status": "DONE",
      "priority": "HIGH",
      "completedAt": "2026-06-07T14:22:01.444Z",
      "completedBy": "Mike Rivera",
      "completionNote": "Re-tightened all four bolts; tested by leaning hard against the rail",
      "completionPhotoUrl": "https://files.sitevisit.app/...",
      "evidenceImageUrls": ["...", "..."],
      "isTest": false,
      "...": "...full ActionItemDto"
    }
  }
}

`action_item.reopened`

Fires when an item transitions from DONE back to OPEN or IN_PROGRESS. Includes the previous status value.

{
  "id": "evt_a5...",
  "event_type": "action_item.reopened",
  "livemode": true,
  "created_at": "2026-06-07T15:10:00.000Z",
  "data": {
    "action_item": { /* full DTO, status flipped back to OPEN */ },
    "previous_status": "DONE"
  }
}

`action_item.deleted`

{
  "id": "evt_a6...",
  "event_type": "action_item.deleted",
  "livemode": true,
  "created_at": "2026-06-07T16:00:00.000Z",
  "data": {
    "action_item_id": "cai1aB2c3D4e5F6g7H8i9J0k1"
  }
}

Evidence events

`evidence.attached`

Fires when a photo or video clip gets attached to an action item — either as regular evidence (via the capture-token flow during a walkthrough) or as a completion photo (proving the work was done). The target_type field tells you which case it is. For completion photos, evidence.id is null because they don’t get their own EvidenceImage row — they’re stored on the action item’s completionPhotoUrl directly.

{
  "id": "evt_e1...",
  "event_type": "evidence.attached",
  "livemode": true,
  "created_at": "2026-06-07T11:15:32.901Z",
  "data": {
    "evidence": {
      "id": "cev1aB2c3D4e5F6g7H8i9J0k1",
      "action_item_id": "cai1aB2c3D4e5F6g7H8i9J0k1",
      "url": "https://files.sitevisit.app/...",
      "caption": "Close-up of the loose bolt"
    },
    "target_type": "action_item"
  }
}

For a completion photo:

{
  "id": "evt_e2...",
  "event_type": "evidence.attached",
  "livemode": true,
  "created_at": "2026-06-07T14:22:01.601Z",
  "data": {
    "evidence": {
      "id": null,
      "action_item_id": "cai1aB2c3D4e5F6g7H8i9J0k1",
      "url": "https://files.sitevisit.app/...",
      "caption": null
    },
    "target_type": "action_item_completion"
  }
}

Signature verification

Every request carries an X-SiteVisit-Signature header:

X-SiteVisit-Signature: t=1717689600,v1=a3b1c2d4e5f6...

Where v1 is HMAC-SHA256(secret, t + "." + body) hex-encoded. To verify:

Parse t and v1 from the header.
Reject the request if |now - t| > 300 seconds (replay protection).
Compute HMAC-SHA256 over ${t}.${raw_body} with your endpoint’s signing secret.
Constant-time compare your computed value with v1.

Node.js

import crypto from "node:crypto";

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    v1 = parts.get("v1", "")
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

Ruby

require "openssl"

def verify(raw_body, header, secret, tolerance = 300)
  parts = header.split(",").map { |kv| kv.split("=", 2) }.to_h
  t  = parts["t"].to_i
  v1 = parts["v1"]
  return false if (Time.now.to_i - t).abs > tolerance

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{raw_body}")
  OpenSSL::Digest.compare(expected, v1) rescue false
end

Always use a constant-time comparison (crypto.timingSafeEqual, hmac.compare_digest, OpenSSL::Digest.compare). A naive === leaks the secret’s length and trailing bytes via timing side-channels.

Retry behavior

If your endpoint returns anything other than a 2xx status (or times out — we cap at 10 seconds), we’ll retry with this backoff:

Attempt	After
1	enqueue (immediate)
2	+1 min
3	+5 min
4	+15 min
5	+1 h
6	+6 h

After 6 failed attempts (~7 hours total), we mark the delivery abandoned. The Settings → Webhooks delivery log surfaces the last response we got so you can debug.

Best practices for your receiver

Dedupe on event.id. Webhook delivery is at-least-once, not exactly-once. Persist the IDs you’ve processed and skip duplicates.
Verify the signature on every request, before doing any work. Forged requests look identical to real ones at the HTTP level.
Branch on livemode before mutating production state. Live and test events both reach a single endpoint URL only if you configured the endpoint that way — but having an explicit if (!livemode) return ok(); short-circuit in your live handler is cheap insurance against misconfigured endpoints.
Respond fast. Acknowledge with a 200 within a few seconds and do real work asynchronously. We treat anything longer than 10s as a failure and queue a retry.
Subscribe to all events on first integration. Filter on your side. Adding subscriptions later requires updating the endpoint config, which is a deploy in your world; ignoring an event you didn’t want is a one-liner.

Disabling / deleting an endpoint

From the dashboard: Settings → Developers → Webhooks → click Disable to soft-suspend (preserves config + delivery history but stops new deliveries), or Delete to remove entirely (cascades to delivery rows). Either takes effect on the next cron tick (~60s). Via the API:

# Soft-disable
curl -X PATCH https://sitevisit.app/api/v1/webhook-endpoints/<id> \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'

# Delete
curl -X DELETE https://sitevisit.app/api/v1/webhook-endpoints/<id> \
  -H "Authorization: Bearer sv_live_..."

Testing your handler before going live

The dashboard’s Send test button (per endpoint) fires a synthetic test.ping event through the real delivery pipeline. The envelope shape is identical to a real event, so if your code handles the test ping correctly, it’ll handle real events correctly too. The test.ping event is not in the regular event catalog and is only emitted by the explicit dashboard button — it’ll never fire from normal account activity.

Get started

Concepts

Account

AI integration

Webhooks

Setting up an endpoint

Event catalog

Payload envelope

Test mode

Event payload reference

Property events

`property.created`

`property.updated`

`property.deleted`

Site visit events

`site_visit.created`

`site_visit.updated`

`site_visit.processing`

`site_visit.ready`

`site_visit.sent`

`site_visit.completed`

`site_visit.deleted`

Action item events

`action_item.created`

`action_item.updated`

`action_item.assigned`

`action_item.completed`

`action_item.reopened`

`action_item.deleted`

Evidence events

`evidence.attached`

Signature verification

Node.js

Python

Ruby

Retry behavior

Best practices for your receiver

Disabling / deleting an endpoint

Testing your handler before going live

​Setting up an endpoint

​Event catalog

​Payload envelope

​Test mode

​Event payload reference

​Property events

​property.created

​property.updated

​property.deleted

​Site visit events

​site_visit.created

​site_visit.updated

​site_visit.processing

​site_visit.ready

​site_visit.sent

​site_visit.completed

​site_visit.deleted

​Action item events

​action_item.created

​action_item.updated

​action_item.assigned

​action_item.completed

​action_item.reopened

​action_item.deleted

​Evidence events

​evidence.attached

​Signature verification

​Node.js

​Python

​Ruby

​Retry behavior

​Best practices for your receiver

​Disabling / deleting an endpoint

​Testing your handler before going live

Setting up an endpoint

Event catalog

Payload envelope

Test mode

Event payload reference

Property events

`property.created`

`property.updated`

`property.deleted`

Site visit events

`site_visit.created`

`site_visit.updated`

`site_visit.processing`

`site_visit.ready`

`site_visit.sent`

`site_visit.completed`

`site_visit.deleted`

Action item events

`action_item.created`

`action_item.updated`

`action_item.assigned`

`action_item.completed`

`action_item.reopened`

`action_item.deleted`

Evidence events

`evidence.attached`

Signature verification

Node.js

Python

Ruby

Retry behavior

Best practices for your receiver

Disabling / deleting an endpoint

Testing your handler before going live