---
title: "Webhooks"
canonical_url: https://developer.repebble.com/index-01/webhooks/
last_updated: 2026-10-11
sdk_version: 4.44
---
# Webhooks

Source: https://developer.repebble.com/index-01/webhooks/

**Notice**  

This page is generated from [`INDEX_WEBHOOK_API.md`](https://github.com/coredevices/mobileapp/blob/f324f3fd08fcc217d5a9d89c81a8fb59cbfbb7cc/experimental/src/commonMain/kotlin/coredevices/ring/external/indexwebhook/INDEX_WEBHOOK_API.md) in the [Pebble mobile app repository](https://github.com/coredevices/mobileapp) at commit [f324f3fd0](https://github.com/coredevices/mobileapp/commit/f324f3fd08fcc217d5a9d89c81a8fb59cbfbb7cc). Relative paths refer to that directory. Changes belong in that repository.

Send Index ring recording data to any HTTP endpoint.

## Setup

1. In Index 01 Settings, tap **Webhook**
2. Pick the gesture to configure: **Hold & talk** or **Double click & hold**. Each gesture has its own endpoint, headers and payload mode
3. Enter your webhook URL
4. Add any request headers you need (e.g. an auth header)
5. Optionally enable **Sign requests** and enter the same signing secret used by your server
6. Choose what to send: Recording only, Transcription only, or Both
7. Optionally tap **Send test event** to verify the endpoint, then **Save**

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**.

## Request Format

```
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)
```

## Multipart Fields

### `audio` (conditional)

Included when payload mode is **Recording only** or **Both**.

- Content-Type: `audio/mp4`
- Filename: `<recordingId>.m4a`
- Format: AAC-LC encoded in M4A container, mono, 16kHz

### `transcription` (conditional)

Included when payload mode is **Transcription only** or **Both**.

- Plain text transcription of the recording

### `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"`.

## Payload Modes

| Mode | `audio` | `transcription` | `recordedAt` | `client` |
| --- | --- | --- | --- | --- |
| Recording only | Yes | No | Yes | Yes |
| Transcription only | No | Yes | Yes | Yes |
| Both | Yes | Yes | Yes | Yes |

## Headers

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-Token` header.

## Protocol versioning

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.

- **Version 1:** Current multipart request contract and optional HMAC-SHA256 signing protocol documented below.

## Signed requests

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:

1. Require HTTPS.
2. Read the raw request body before parsing multipart fields.
3. Reject unsupported webhook versions and malformed timestamps.
4. Reconstruct the signed bytes and compare signatures in constant time.
5. Reject timestamps outside a short window; five minutes is a reasonable default.
6. Cache accepted delivery IDs for at least that window, and answer a repeated ID with a 2xx without processing it again. The app retries any delivery for which it did not receive a successful response.

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.

## Other authentication

Custom headers can still carry another authentication scheme alongside request signing. The original integration used an `X-Widget-Token` header, but any scheme works.

## Example: Verifying a signed request

```
import hashlibimport hmacimport osimport timefrom flask importFlask,requestapp=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'ifwebhook\_version!='1':return'Unsupported webhook version',400try:timestamp=int(timestamp\_text)exceptValueError:return'Invalid timestamp',400now=int(time.time())ifabs(now-timestamp)\>300:return'Expired request',401prefix=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()ifnothmac.compare\_digest(expected,signature):return'Invalid signature',401ifdelivery\_idinseen\_deliveries:return'Already received',200seen\_deliveries[delivery\_id]=nowaudio=request.files.get('audio')transcription=request.form.get('transcription')recorded\_at=request.form.get('recordedAt')trigger=request.headers.get('X-Index-Trigger')ifaudio:audio.save(f'/tmp/{audio.filename}')print(f'Received audio: {audio.filename}')iftranscription: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.

## Notes

- Uploads are async and non-blocking — they don't delay the normal recording pipeline
- Network errors and HTTP 408, 429 and 5xx responses are retried every minute, up to 10 attempts, including after the app restarts. A delivery that still fails can be sent again with **Retry** in **Recent runs**
- The webhook fires as early as its payload allows, in parallel with the rest of the pipeline: `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.
- Audio is the same 16kHz resampled version used for transcription
