Nest Engineering Docs
Webhooks

Interfaces

Inbound and outbound contracts for Webhooks

Authentication

  • All endpoints require X-API-Key except GET /api/v1/health.
  • Keys are loaded from Secret Manager (WEBHOOKS_API_KEY) at startup.
  • Missing or invalid keys return 401 Unauthorized.

Base path

  • v1: /api/v1

Endpoint catalog

ResourceOperationsNotes
/healthGETHealth check (no auth)
/invoicesPOSTPartner invoice webhook (queues Cloud Task)
/tasks/{task_id}GETCloud Tasks status lookup
/nest-bubPOSTBubble-triggered sync event

Required headers

  • X-API-Key (all non-health requests)
  • Idempotency-Key and X-Organization-Id (invoice webhooks)

Response behavior

  • Successful webhook submissions return 202 Accepted with task metadata.
  • Invalid payloads return 4xx errors with details.
  • Invoice webhooks are currently allowlisted to specific organizations; update the allowlist in code when onboarding new partners.

Outbound dependencies

  • Cloud Tasks targets the Handler service.
  • Secret Manager for API keys and optional Sentry DSN.

Last updated on

Runbooks

Operational playbooks for Webhooks

Configuration

Runtime configuration and environment variables for Webhooks