Webhooks

This page is the reference for what VerifyAI sends to your webhook endpoints: the request, its headers, each event's payload, and how failed deliveries are retried.

For a walkthrough — adding an endpoint, verifying signatures in code, a production handler — see Setting up webhooks.

Managing endpoints

Endpoints are managed in the dashboard under Settings → Webhooks. There is no public REST API for creating, listing or deleting them. From the dashboard you can:

• Add an endpoint: an HTTPS URL (not a private or loopback address) and the events it receives. The signing secret (whsec_…) is shown once, when the endpoint is added.
• Edit events on an existing endpoint.
• Send test event: deliver a signed webhook.test event to one endpoint and see its response.
• Read the delivery log: each endpoint's 20 most recent deliveries, with status, attempts, and the HTTP status and body your endpoint returned.
• Redeliver a failed or retrying delivery immediately.
• Use the VerifyAI test receiver: a built-in endpoint that accepts every delivery and reports whether the signature verified, so you can see real deliveries before you have a server.
• Delete an endpoint. Deliveries to it stop.

The request

Every delivery is an HTTPS POST with a JSON body:

The body is { "event": "<name>", "data": { … } }. Events other than verification.completed also carry a top-level created_at.

Verify the signature over the raw body before parsing it, reject a t more than a few minutes from your clock, and compare in constant time. See Verify the signature.

Responses and retries

Retries are processed on a schedule, so one can arrive shortly after it is due. A failed delivery can be redelivered from the dashboard at any time. Each attempt is signed with a fresh t.

Events

verification.completed

{
  "event": "verification.completed",
  "data": {
    "id": "ver_3aF92k1m",
    "created_at": "2026-10-08T14:55:02Z",
    "status": "success",
    "is_compliant": false,
    "confidence": 0.91,
    "policy": "pol_handoff_exterior",
    "category": "damage_noted",
    "violation_reasons": ["no_visible_damage"],
    "feedback": "Scratch on the rear bumper, left of the plate.",
    "warning_violation_reasons": [],
    "warning_feedback": null,
    "damage_findings": [
      {
        "finding_id": "f1",
        "panel": "car_rear_bumper",
        "damage_type": "scratch",
        "severity": "light",
        "severity_score": 0.3,
        "bbox": [0.41, 0.62, 0.55, 0.68],
        "area_pct": 0.04,
        "confidence": 0.86
      }
    ],
    "overall_severity": "light",
    "metadata": {
      "reference_id": "LOAN-48213",
      "stage": "pickup",
      "inspection_session_id": "9c2e7b41-0f3a-4d58-8e6b-1a2b3c4d5e6f",
      "inspection_slot": "rear",
      "channel": "web"
    },
    "image_url": "<signed URL, valid for 1 hour>"
  }
}

inspection.submitted and inspection.reviewed

data is the inspection, the same object GET /api/v1/inspection-sessions/{id} returns. Photo and PDF links in a webhook are signed for 7 days. A complete example is in Sending an inspection link.

inspection.decision

Sent for inspections created with lending. data is the same decision GET /api/v1/inspection-sessions/{id}/decision returns, plus the inspection's identifiers. See Vehicle inspection integration for every field.

webhook.test

{
  "event": "webhook.test",
  "created_at": "2026-10-08T12:00:00.000Z",
  "data": { "message": "Test event from VerifyAI", "webhook_id": "3f0c9a7e-…" }
}

What's next

• Setting up webhooks — verify signatures, handle retries, and ship a production handler.
• Sending an inspection link — the flow behind the inspection.* events.
• Concepts: Verifications — the object behind verification.completed.