Skip to main content

Monitors

POST /v1/monitors​

Create a monitoring subscription for an entity.

Request​

{
  "entity_id": "ent_01abc...",
  "checks": ["sam_registration", "tin_match"],
  "frequency": "daily",
  "webhook_url": "https://yourapp.com/webhooks/vendorval"
}

Response — 201​

{
  "id": "mon_01...",
  "entity_id": "ent_01abc...",
  "checks": ["sam_registration", "tin_match"],
  "frequency": "daily",
  "webhook_url": "https://yourapp.com/webhooks/vendorval",
  "status": "active",
  "created_at": "2026-04-19T12:00:00Z"
}

GET /v1/monitors​

List all active monitors for your organization.

DELETE /v1/monitors/:id​

Cancel a monitor subscription. No further re-verification runs will be scheduled.

GET /v1/monitors/:id/events​

Returns the history of detected changes for this monitor, newest first.

Response — 200​

{
  "events": [
    {
      "id": "evt_01...",
      "monitor_id": "mon_01...",
      "changes": [
        {
          "field": "sam_registration.registration_status",
          "previous": "active",
          "current": "expired"
        }
      ],
      "verification_id": "ver_02...",
      "detected_at": "2026-04-20T06:00:00Z"
    }
  ]
}

Webhook delivery​

VendorVal uses pg-boss for webhook delivery with idempotency keys. If your endpoint returns a non-2xx status, delivery is retried with exponential backoff (up to 24 hours).

Webhook payload shape​

{
  event: "monitor.change_detected"
  monitor_id: string
  entity_id: string
  changes: Array<{
    field: string
    previous: string | null
    current: string | null
    detected_at: string
  }>
  verification_id: string
  delivered_at: string
}

Securing webhooks​

Verify the X-VendorVal-Signature header against your webhook secret (configurable in the Dashboard).