Skip to main content

Case Webhook Payloads

CareValidate can send real-time updates to your system using webhooks.
Once you configure an endpoint URL, our platform will securely notify your service whenever a patient case progresses through different stages such as:

  • Case creation
  • Doctor prescription
  • Payment updates
  • Shipment status changes

Webhook Setup​

To configure a webhook:

  1. Navigate to Organization Settings
  2. Open the API tab
  3. Go to the Webhook section
  4. Click Add to register a new webhook endpoint

Adding a Webhook​

When creating a webhook, select the Document Format:

  • BASE64 — Documents are included directly in the webhook payload.
  • URL — The payload contains a signed document URL.

Signed URLs remain valid for 15 minutes from the time they are generated.

Secret Key (Optional)​

You may optionally configure a secret key to verify webhook authenticity.

When enabled, CareValidate includes an x-cv-signature header with every webhook request. This signature can be used to validate that the payload was sent by CareValidate and was not modified in transit.

⚠️ Important:
Do not use JSON body-parsing middleware before verifying the signature.
Any modification to the raw request body will cause signature validation to fail.

Signature Verification (Node.js Example)​

const receivedSignature = request.headers['x-cv-signature']

const expectedSignature = createHmac('sha256', secretKey)
  .update(JSON.stringify(sentData), 'utf-8')
  .digest('hex')

const isValid = timingSafeEqual(
  Buffer.from(expectedSignature, 'hex'),
  Buffer.from(receivedSignature, 'hex')
)

There are two options for the webhook payload. You can change your preference from the Organization settings tab using Send Full Case Data Field.

Payload Options​

  • Full Case Data With this option, every event payload will have full case details including all decisions, communications, documents, payments, and activity logs.

  • Only Event Data When a case has more interactions, the full payload size can increase drastically. This option sends only basic case info and event-related objects, based on the specific events that occur.

The following documents detail the format of the call that you will receive at your endpoint URL for each option.