🪝 Webhooks

🚧 Coming Soon: Webhook functionality is currently in development.

Webhooks allow you to receive real-time HTTP notifications when events occur, eliminating the need to poll for results.

Overview

Instead of continuously polling the API for analysis completion, you can register a webhook URL that will receive a POST request when processing finishes.

Benefits of Webhooks

• Real-time notifications - Get instant updates when processing completes
• Reduced API calls - No need to poll every few seconds
• Lower latency - React immediately to completion events
• Better scalability - Handle high volumes without polling overhead

Planned Features

Event Types

The following webhook events are planned:

| Event | Description | |-------|-------------| | scan.completed | Video analysis successfully completed | | scan.failed | Video analysis failed | | scan.started | Video upload received and processing started |

Webhook Payload

When an event occurs, the API will send a POST request to your webhook URL:

{
  "event": "scan.completed",
  "timestamp": "2025-10-26T12:34:56.789Z",
  "session_id": "sess_20251026123456_abc123",
  "data": {
    "vitals": {
      "heart_rate": 72.5,
      "respiratory_rate": 16.2,
      "hrv": 45.3,
      "blood_pressure": null,
      "confidence": 0.89,
      "timestamp": "2025-10-26T12:34:56.789Z",
      "processing_time_ms": 32450
    }
  },
  "signature": "sha256=abcdef123456..." 
}

Planned Implementation

Registering a Webhook

// Future API
const client = new RPPGClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.yourdomain.com/api',
  webhookUrl: 'https://yourserver.com/webhooks/rppg'
});

// Or per-session
const session = await client.createSession({
  webhookUrl: 'https://yourserver.com/webhooks/rppg'
});

Webhook Endpoint Example

// Express.js webhook handler (planned)
const express = require('express');
const crypto = require('crypto');

app.post('/webhooks/rppg', express.json(), (req, res) => {
  const payload = req.body;
  const signature = req.headers['x-rppg-signature'];
  
  // Verify signature (recommended)
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  if (`sha256=${expectedSignature}` !== signature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle event
  if (payload.event === 'scan.completed') {
    const { session_id, data } = payload;
    console.log(`Session ${session_id} completed:`);
    console.log('Heart Rate:', data.vitals.heart_rate);
    
    // Update your database, notify user, etc.
    updateDatabase(session_id, data.vitals);
  }
  
  // Acknowledge receipt
  res.status(200).send('OK');
});

Security

Webhooks will be secured with:

1. Signature verification - HMAC-SHA256 signature in X-RPPG-Signature header
2. IP whitelisting - Optional restriction to known IP ranges
3. HTTPS only - Webhooks must use HTTPS endpoints
4. Retry logic - Failed deliveries will be retried with exponential backoff

Retry Behavior

If your webhook endpoint returns an error (non-2xx status code):

1. Immediate retry
2. Retry after 5 seconds
3. Retry after 30 seconds
4. Retry after 5 minutes
5. Retry after 30 minutes
6. Final retry after 2 hours

After 6 failed attempts, the webhook event will be marked as failed and logged.

Alternative: Polling (Current Method)

Until webhooks are available, use the polling approach:

// Current implementation - polling
const vitals = await client.waitForVitals(sessionId, {
  pollingInterval: 3000,  // Check every 3 seconds
  maxPollingTime: 180000  // Give up after 3 minutes
});

Or implement your own polling:

async function pollForResults(sessionId) {
  while (true) {
    const response = await client.getVitals(sessionId);
    
    if (response.status === 'completed') {
      return response.vitals;
    } else if (response.status === 'failed') {
      throw new Error(response.error);
    }
    
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

Timeline

Webhook functionality is planned for release in Q1 2026.

To be notified when webhooks are available, please contact your account manager or watch for updates in the API Changelog.

Questions?

If you have specific webhook requirements or use cases, please reach out to support@yourdomain.com to help inform the webhook implementation.

---

Next Steps

• Testing & Sandbox → - Test your integration
• Rate Limits → - Understand API quotas
• API Reference → - Current polling implementation