This page is generated from INDEX_WEBHOOK_API.md in the Pebble mobile app repository at commit 6361b3310. Relative paths refer to that directory. Changes belong in that repository.
Send Index ring recording data to any HTTP endpoint.
A gesture only sends once its config is saved with a URL. The switch turns sending off without discarding the URL and headers, and the last 20 runs per gesture are listed under Recent runs.
POST <your webhook URL>
Content-Type: multipart/form-data; boundary=<uuid>
<each user-configured header>
X-Audio-Size: <byte count> (when audio is included)
X-Index-Webhook-Version: 1
X-Index-Trigger: single-click-hold | double-click-hold | test-event
X-Index-Test: true (test events only)
X-Index-Delivery: <stable delivery ID>
X-Index-Signature: <lowercase hex HMAC-SHA256> (when signing is enabled)
X-Index-Timestamp: <Unix time in seconds> (when signing is enabled)
audio (conditional)Included when payload mode is Recording only or Both.
audio/mp4<recordingId>.m4atranscription (conditional)Included when payload mode is Transcription only or Both.
test (test events only)Set to "true" for payloads sent by Send test event, so they cannot be mistaken for a recording. Test events carry no audio part and a fixed transcription.
recordedAt (always)Unix timestamp in milliseconds when the recording was captured.
client (always)Always set to "ring".
| Mode | audio |
transcription |
recordedAt |
client |
|---|---|---|---|---|
| Recording only | Yes | No | Yes | Yes |
| Transcription only | No | Yes | Yes | Yes |
| Both | Yes | Yes | Yes | Yes |
Headers are fully user-configurable in the webhook settings — add as many name/value pairs as you need. They are sent verbatim on every request, so use them for authentication (e.g. an Authorization or X-Widget-Token header) or any other metadata your server expects.
X-Audio-Size is still added automatically when audio is included (it carries the audio byte count) and cannot be overridden.
X-Index-Trigger is added automatically to identify the gesture that started the recording — single-click-hold, double-click-hold, or test-event for a manually sent test. The gesture is persisted with the processing task and preserved when a failed recording is retried. Recordings with no known gesture do not fire a webhook at all.
X-Index-Webhook-Version is sent on every request and versions the complete webhook protocol, including its automatic headers, multipart fields, and signing rules. This document describes version 1. A missing version identifies a request from an older, pre-version app build; receivers that depend on a particular contract should require a supported explicit version.
X-Index-Delivery identifies a recording: it is the same every time that recording is delivered, so a receiver can use it to drop duplicates. Test and button events get a fresh UUID.
User-configured headers cannot override X-Audio-Size, X-Index-Webhook-Version, X-Index-Trigger, X-Index-Test, X-Index-Signature, X-Index-Timestamp, or X-Index-Delivery. Header-name matching is case-insensitive.
Migration note: a previously configured single webhook is copied to both recording gestures, and an auth token configured before headers were user-settable is carried over as an
X-Widget-Tokenheader.
Increment X-Index-Webhook-Version only for receiver-visible breaking changes, such as renaming or removing automatic headers or multipart fields, changing field semantics or encoding, or changing the signed-byte format. Backward-compatible additions remain on the current version; receivers should ignore headers and multipart fields they do not use.
Record every version change in this document, including migration guidance when applicable.
Request signing is optional and configured independently for each recording gesture. The secret is stored in Android Keystore-backed encrypted storage or Apple Keychain, rather than in the normal webhook settings JSON. If signing is enabled but the secret cannot be read, the request fails without sending an unsigned fallback.
The app signs these exact bytes:
UTF8(
"v1\n" +
timestamp + "\n" +
deliveryId + "\n" +
trigger + "\n" +
(isTest ? "1" : "0") + "\n"
) || rawMultipartBodyBytes
The signing key is the UTF-8 byte sequence of the secret exactly as entered. The signature header is:
X-Index-Signature: <lowercase hex HMAC-SHA256(signingKey, bytesAbove)>
The leading v1 in the signed bytes authenticates X-Index-Webhook-Version: 1; a receiver must use the header value to reconstruct that prefix. For a recording, X-Index-Delivery is the stable recording delivery identifier. A test event gets a fresh UUID. X-Index-Timestamp is generated when the request is sent.
Receivers should:
Use a unique, cryptographically random secret for each endpoint. At least 32 random bytes encoded as base64url or hex is recommended. Do not use a memorable password or reuse an API token.
HMAC authenticates the request and detects modification; it does not encrypt the recording or transcription. HTTPS is still required.
Custom headers can still carry another authentication scheme alongside request signing. The original integration used an X-Widget-Token header, but any scheme works.
import hashlib
import hmac
import os
import time
from flask import Flask, request
app = Flask(__name__)
secret = os.environ["INDEX_WEBHOOK_SECRET"].encode("utf-8")
seen_deliveries = {}
@app.route('/webhook', methods=['POST'])
def receive():
raw_body = request.get_data(cache=True)
webhook_version = request.headers.get('X-Index-Webhook-Version', '')
signature = request.headers.get('X-Index-Signature', '')
timestamp_text = request.headers.get('X-Index-Timestamp', '')
delivery_id = request.headers.get('X-Index-Delivery', '')
trigger = request.headers.get('X-Index-Trigger', '')
is_test = request.headers.get('X-Index-Test') == 'true'
if webhook_version != '1':
return 'Unsupported webhook version', 400
try:
timestamp = int(timestamp_text)
except ValueError:
return 'Invalid timestamp', 400
now = int(time.time())
if abs(now - timestamp) > 300:
return 'Expired request', 401
prefix = f"v{webhook_version}\n{timestamp}\n{delivery_id}\n{trigger}\n{1 if is_test else 0}\n"
expected = hmac.new(
secret,
prefix.encode('utf-8') + raw_body,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(expected, signature):
return 'Invalid signature', 401
if delivery_id in seen_deliveries:
return 'Already received', 200
seen_deliveries[delivery_id] = now
audio = request.files.get('audio')
transcription = request.form.get('transcription')
recorded_at = request.form.get('recordedAt')
trigger = request.headers.get('X-Index-Trigger')
if audio:
audio.save(f'/tmp/{audio.filename}')
print(f'Received audio: {audio.filename}')
if transcription:
print(f'Transcription: {transcription}')
print(f'Recorded at: {recorded_at}')
print(f'Trigger: {trigger}')
return 'OK', 200
The in-memory replay cache above is only illustrative. A production service should expire entries and use a shared TTL store when more than one server instance accepts webhooks.
RecordingOnly sends as soon as the audio is on disk (before transcription); modes that include the transcript send once it is transcribed, concurrently with agent processing. The webhook therefore fires even if agent processing (or, for the recording-only mode, transcription) later fails.