Overview

What Are Webhooks?

Webhooks allow your application to receive real-time HTTP push notifications when specific events occur within the Novee platform. Instead of continuously polling the API for updates, you register a URL and Novee will POST event data to your endpoint as events happen.

How It Works


┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
│  Novee Platform │──────▶ │  Webhook System │──────▶ │  Your Server    │
│  (Event Source) │ emit   │  (Delivery)     │ POST   │ (Registered URL)│
└─────────────────┘        └─────────────────┘        └─────────────────┘

Flow

Register — You register a webhook URL and choose which event types to subscribe to, scoped to a Project.
Event Occurs — An event (e.g., a fall detection alert or vital threshold breach) happens for a user associated with your project.
Delivery — Novee sends an HTTP POST request to your registered URL with the event payload, signed with HMAC-SHA256.
Verification — Your server verifies the signature using the shared secret to confirm authenticity.
Processing — Your application processes the event data and returns a 2xx response.

Key Concepts

Project

Webhooks are scoped to a Project. A project is a logical grouping within Novee that associates users and resources. When you register a webhook, you bind it to a specific projectId. All events for users belonging to that project will be delivered to the registered webhook URL.

Each project can have one webhook registration.
You can subscribe to multiple event types per registration.

Webhook Secret

When you register a webhook, the system generates a secret (prefixed with whsec_). This secret is used to create HMAC-SHA256 signatures for every payload sent to your endpoint. Store this secret securely — it is only returned once at registration time, and it is encrypted at rest in Novee’s database.

Event Types

Novee currently supports the following webhook event types:

Type	Enum Value	Description
Emergency (Fall Detection)	`FALL_DETECTION`	Triggered when a fall or emergency event is detected for a user.
Vital Threshold	`VITAL_THRESHOLD`	Triggered when a user’s vital signs cross a configured threshold.
Test	`TEST`	A test event used to verify your webhook endpoint is working correctly.

Delivery Format

All webhook deliveries are HTTP POST requests with:

Content-Type: application/json
X-Timestamp: Unix timestamp (milliseconds) of when the payload was signed
X-Signature: HMAC-SHA256 hex digest of {timestamp}.{payload}

See Security & Signature Verification for full details.