Web Hooks

Web hooks let Prima notify your systems in real time. When lab data changes or an item reaches a workflow milestone, Prima sends an HTTP POST with a JSON payload to a URL you register, so you can react without polling the API.

Quick Start

  1. Go to Admin → Web Hook Subscriptions and create a subscription.
  2. Enter the destination URL of the endpoint that will receive notifications.
  3. Select the events you want to be notified about.
  4. Have your endpoint read the JSON payload, return 200 OK quickly, and process asynchronously.

How notifications work

  • Two families of notification. CRUD notifications fire when an entity is added, modified, or deleted. Lifecycle event notifications fire when an item reaches a workflow milestone (for example, a slide is stained or a cassette is embedded).
  • Ordered, per subscription. Notifications for a single subscription are delivered one at a time, in the order they occurred.
  • Reliable delivery with retries. Each notification is queued and retried with an increasing back-off until your endpoint accepts it, so brief outages on your side will not lose events. Each attempt times out after 30 seconds.
  • At-least-once delivery. Because failed attempts are retried, your endpoint may occasionally receive the same notification more than once. Use the MessageId field to de-duplicate and make processing idempotent.
  • Respond quickly. Return a 2xx status as soon as you have accepted the message, then do any slow work asynchronously. A slow endpoint will hit the 30-second timeout and be retried.

Documentation

Event Types

The full list of events you can subscribe to — CRUD operations on cases, specimens, cassettes, slides, studies, and animals, plus lifecycle events.

Payload Format

The structure of the JSON Prima posts to your endpoint, including the common envelope fields and the entity carried by each notification type.

Examples

Sample notification payloads and a minimal C# endpoint that receives them and de-duplicates on MessageId.