Webhooks

Webhooks notify your system when events occur in VectorCare.

Setup

Log into VectorCare as an account admin
Navigate to Settings → Open API
Set your webhook URL (must be HTTPS)

Webhook Format

{
  "event_id": "EVENT_ID",
  "event_type": "request.status.available",
  "event": {
    "request_id": "ABCD1234",
    "request_current_state": "accepted"
  }
}

Field	Description
`event_id`	Unique ID for deduplication
`event_type`	Type of event (see below)
`event`	Event payload

Event Types

Event Type	Description
`request.state.available`	Request is available to your account
`request.state.unavailable`	Request is no longer available
`request.data.updated`	Request data was modified
`request.state.pending`	Request was broadcast (limited data)

Headers

Header	Description
`VectorCare-Environment`	`development` or `production`
`VectorCare-Namespace`	`vectorcare` or `kaiser`
`X-VectorCare-Signature`	Signature for verification

Standing Order Webhooks

For standing orders, you may receive bulk webhooks:

{
  "event_id": "EVENT_ID",
  "event_type": "collection.state.updated",
  "event": {
    "collection_id": "STANDING_ORDER_ID",
    "collection_current_state": "accepted",
    "request_ids": ["ABCD1234", "EFGH5678", "IJKL9012"]
  }
}

Verification

Verify webhooks using RSA-SHA256 with the public key from your VectorCare Open API settings. Base64 decode the X-VectorCare-Signature header and verify it against the raw request body.

Best Practices

Respond within 10 seconds with a 2xx status
Use async processing for heavy work
Deduplicate using event_id
Set unique constraint on request_id
Avoid rate limiting webhook requests

Retry Behavior

Attempt	Delay
1st	Immediate
2nd	8 seconds
3rd	64 seconds

Pending State Webhooks

For request.state.pending webhooks, these fields are omitted to protect PHI:

transport_pickup_time
transport_agreed_for_time
enabled_patient_fields
enabled_request_fields
patient_dob

Pending requests may expire without becoming available.