Nest Engineering Docs
Handler

Interfaces

Inbound and outbound contracts for Handler

Authentication

  • Internal ingress only. Cloud Tasks requests must be authorized at the infrastructure layer (service account and IAM).
  • No API key middleware is used in this service.

Base path

  • v1: /api/v1

Endpoint catalog

ResourceOperationsNotes
/healthGETHealth check
/{vendor}/{resource}POSTDynamic pipeline endpoints (PIMS ETL)
/webhooks/invoicesPOSTBubble invoices webhook task
/webhooks/nest-bubPOSTBubble trigger event task

Dynamic pipeline endpoints

Pipeline endpoints are generated from the registry and follow the pattern: /api/v1/{vendor}/{resource} where vendor is one of ezyvet, bitwerx, or hap and resource maps to a pipeline name (e.g., patients, invoices).

Request body (PIMS pipelines)

Pipelines accept a TaskInfo payload that includes:

  • organization_id, organization_name, identifier
  • pipeline_name, last_modified, commit_timestamp_ms
  • clinics list for multi-clinic orgs

Common headers

  • X-CloudTasks-TaskName and X-CloudTasks-QueueName are logged for tracing.
  • X-Nest-StreamFirstExecutionTime (optional) is used for retry escalation logs.

Response

  • Success responses are typically 204 No Content.
  • Failures return 500 with a pipeline-specific error message.

Webhook endpoints

/webhooks/invoices expects:

  • Headers: Idempotency-Key, X-Organization-Id
  • Body: WebhookInvoicesRequest (list of invoices + line items, up to 100)

/webhooks/nest-bub expects:

  • Headers: Idempotency-Key, X-Organization-Id
  • Body: RawEvent with entity, action, and data

Outbound dependencies

  • Cloud Spanner for reads/writes.
  • PartnerCreds service for partner tokens (PIMS access).
  • Bubble API for invoice forwarding (Cloud Tasks).

Last updated on

Runbooks

Operational playbooks for Handler

Configuration

Runtime configuration and environment variables for Handler