Nudge Doorbell Integration — Architecture & Data Flow

Nudge Doorbell Integration — Architecture & Data Flow

Last updated: [publish date]

This document describes the architecture, data flow, and storage for the Nudge ↔
Ring doorbell integration, developed by Bolton LLC. The integration plays a chime
on a user's Sonos speakers when their Ring doorbell is pressed. It receives ONLY
the doorbell-press event — never video, audio, images, live view, or recordings.

System architecture

flowchart LR
  Ring["Ring (cloud)"] -->|"button_press webhook · HTTPS + HMAC"| DW["Nudge doorbell Worker"]
  DW <-->|"encrypted read/write"| KV[("Cloudflare KV · US · AES-256-GCM")]
  DW -->|"mint token · internal HMAC"| AC["access-control Worker"]
  AC -->|"Sonos access token"| DW
  DW -->|"play audio clip · HTTPS"| Sonos["Sonos Control API → speakers"]

Runtime flow — a doorbell press

sequenceDiagram
  autonumber
  participant Ring as Ring (cloud)
  participant DW as Nudge doorbell Worker
  participant KV as Cloudflare KV (encrypted)
  participant AC as access-control Worker
  participant Sonos as Sonos Control API
  Ring->>DW: button_press webhook (HTTPS, HMAC-SHA256 signed)
  DW->>DW: verify X-Signature · dedupe on request_id
  DW->>KV: account_id → household + chime config
  DW->>AC: mint Sonos token (internal, HMAC-signed)
  AC-->>DW: Sonos access token
  DW->>Sonos: play audio clip (Bearer) on selected speakers
  Note over DW,Sonos: No Ring data sent to Sonos. No video/audio ever received.

Account-linking flow — one-time

sequenceDiagram
  autonumber
  actor User
  participant Ring as Ring (cloud)
  participant DW as Nudge doorbell Worker
  participant KV as Cloudflare KV (encrypted)
  User->>Ring: Install/connect Nudge, select doorbell
  Ring->>DW: OAuth authorization code → Token Exchange URL
  DW->>Ring: exchange code (oauth.ring.com/oauth/token)
  DW->>Ring: GET /v1/users/me → account_id
  DW->>KV: park encrypted tokens (unclaimed)
  Ring->>User: redirect to account-link page (nonce, time)
  User->>DW: sign in with link code
  DW->>DW: validate time window · match nonce → parked token
  DW->>Ring: App-Integrations POST + PATCH (confirm link)
  DW->>KV: store account↔household mapping + tokens (encrypted)

Data storage locations and options

• Single storage location: Cloudflare KV, US. No other datastore, no backups
  or exported copies of Ring data are maintained.
• No third-party storage of Ring data: Sonos receives only a "play chime"
  command on the user's own system; it receives no Ring account id or event data.

Security controls (summary)

• All external communication over HTTPS.
• Inbound Ring webhooks are HMAC-SHA256 signature-verified before processing;
  invalid/unsigned requests are rejected (401).
• Tokens encrypted at rest (AES-256-GCM); encryption keys held as Cloudflare
  Worker secrets, never in source.
• The doorbell Worker is isolated; it reaches other services only through one
  narrow, HMAC-signed internal call to obtain a Sonos playback token.
• Logs mask account identifiers.

Contact

support@bolton.llc | Bolton LLC, Massachusetts, USA