Blog

Gencove gives partners the building blocks for a complete consumer genetics product: a partner integration flow covering the full journey, hosted forms for kit ordering and data upload, and variant-level API access to results. Today we are adding the piece that ties the journey together: real-time sample status webhooks. A new sample_status_update event fires on every sample status change, from the moment a kit is ordered, through lab processing and data upload, to the completed analysis. Your product always knows where every sample is, the moment it happens.

Why we built it

A consumer genetics product lives or dies on communication. When an end user orders a kit, they want to know it shipped. When they drop it in the mail, they want to know the lab received it. When something goes wrong, like a wrong address or an expired upload session, your support team wants to know before the user writes in.

Until now, Gencove webhooks answered only the final question: analysis_complete_v2 fires when analysis finishes. Everything before that - the entire kit and lab lifecycle - had to be polled from the API. Polling works, but it means running schedulers, tracking cursors, and accepting a delay between something happening and your product knowing about it. Worse, some of the most actionable states, like a kit order failing due to an invalid address, could only be discovered by polling.

sample_status_update removes that entire class of work. Subscribe once per project, and every status transition is pushed to your endpoint as it is recorded.

What we released

A new project-scoped webhook event type, sample_status_update, that fires on every sample status change: kit ordering and fulfillment, lab receipt and processing, data upload and import, analysis start, and analysis completion.

Subscriptions are managed the same way as existing events, in the Gencove dashboard or via the API, and every subscription can be verified with a test delivery before any real traffic flows.

Following a single sample

Here is a real journey of one sample through a consumer PRS product built on Gencove, as delivered to a webhook endpoint. The end user places their order and the kit lifecycle starts reporting right away with kit requested and kit ordered. When the kit ships:

[
  {
    "event_id": "b7c1d9e4-53a2-4f6e-9b0d-8a4c2e71f5a3",
    "event_type": "sample_status_update",
    "timestamp": "2026-07-28T11:35:04.812311Z",
    "payload": {
      "project": {
        "id": "1d6daca6-475a-4961-9841-57aac36cbd0f"
      },
      "samples": [
        {
          "id": "8a2626dd-322e-4f71-80db-43a826c39577",
          "client_id": "",
          "last_status": {
            "id": "8fd3f7eb-7a37-45cc-ab31-e7d9d1330707",
            "status": "kit shipped",
            "created": "2026-07-28T11:35:04.512873+00:00"
          }
        }
      ]
    }
  }
]

Once the swab reaches the lab (kit received at lab) and the lab finishes, kit result added and kit completed at lab arrive, and the pipeline takes over without a pause: scheduled, importing, running, and finally succeeded. Each transition arrives as its own event, so your product can reflect every step to the end user in real time, with no polling loop anywhere. Purely internal machine states between those steps are never delivered; your endpoint only sees statuses that mean something to your product.

Batched events for bulk operations

When many samples change status in one operation - a bulk import, a run starting, a run completing - the transitions are delivered together in one event rather than as a webhook per sample. One event can carry many samples and their statuses can differ. Here is a run finishing with mixed outcomes:

[
  {
    "event_id": "5a344629-23a8-4b7c-98e6-b64828379151",
    "event_type": "sample_status_update",
    "timestamp": "2026-09-02T16:35:41.576436Z",
    "payload": {
      "project": {
        "id": "1d6daca6-475a-4961-9841-57aac36cbd0f"
      },
      "samples": [
        {
          "id": "3d0f7a92-6c1e-4b8a-9f24-7e5a1c0d8b46",
          "client_id": "",
          "last_status": {
            "id": "4a8aeaf3-30e4-4e11-9bd4-96e8b9e16a1e",
            "status": "failed qc",
            "created": "2026-09-02T16:35:39.761539+00:00"
          }
        },
        {
          "id": "8a2626dd-322e-4f71-80db-43a826c39577",
          "client_id": "",
          "last_status": {
            "id": "a5d999b2-44d3-4c44-aeff-cc0d20d53d1b",
            "status": "succeeded",
            "created": "2026-09-02T16:35:41.550223+00:00"
          }
        }
      ]
    }
  }
]

The payload schema is shared with analysis_complete_v2, so one parser handles both event types. Writing a robust consumer takes three rules: iterate the samples list rather than assuming a fixed size, deduplicate on last_status.id (delivery is at-least-once), and order by last_status.created (delivery order is not guaranteed). Since final analysis statuses arrive through sample_status_update as well, subscribing to analysis_complete_v2 becomes redundant once you consume this event.

Deliveries carry the same guarantees as all Gencove webhooks: HMAC signatures when a subscription secret is set, automatic retries with backoff on failures, and a full delivery log per subscription in the dashboard.

What this enables

The immediate use case is user-facing status: an order-tracking style experience for genomics - kit shipped, arrived at lab, data ready - inside your own product, driven entirely by pushed events. Beyond that, partners are using status events to trigger their own pipelines the moment results land, to alert support teams on failure states like an undeliverable kit before the end user notices, and to reconcile fulfillment systems against lab reality without a nightly sync job.

The full event reference, payload schemas, and delivery semantics are documented at docs.gencove.com - Event notifications.

With API, OAuth, variant-level access, hosted forms, and now real-time status events, a partner can deliver a complete consumer genetics product, and keep their users informed at every step of it. We build the infrastructure health platforms need to embed genetics into their own products.