Webhooks

Receive signed events when a Voice Note finishes processing or fails.

Webhooks let your server react to a note without polling. Create and manage endpoints from Settings → Notes → Webhooks when that option is available for your account.

Endpoint URLs must be public https:// URLs. Monologue rejects plain HTTP, localhost, and private network addresses.

Verify every signature

Each request includes webhook-id, webhook-timestamp, and webhook-signature headers and is signed according to the Standard Webhooks specification. Verify the raw request body with your endpoint’s whsec_... secret before parsing or processing it.

from fastapi import FastAPI, Request, Response
from standardwebhooks import Webhook, WebhookVerificationError

app = FastAPI()
wh = Webhook("whsec_...")

@app.post("/webhooks/monologue")
async def monologue_webhook(request: Request) -> Response:
    body = await request.body()
    try:
        event = wh.verify(body, dict(request.headers))
    except WebhookVerificationError:
        return Response(status_code=401)

    # Enqueue event for asynchronous processing here.
    return Response(status_code=204)

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.MONOLOGUE_WEBHOOK_SECRET!);

app.post("/webhooks/monologue", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = wh.verify(req.body, req.headers as Record<string, string>);
    res.status(204).end();
    // Enqueue event for asynchronous processing here.
  } catch {
    res.status(401).end();
  }
});

Do not parse and re-serialize JSON before verification. The signature covers the exact request bytes.

Delivery behavior

• Delivery is at least once. Deduplicate using webhook-id, which remains stable across retries.
• Events are not guaranteed to arrive in order. Use the Notes API as the source of truth.
• Return a 2xx within 20 seconds and process heavy work asynchronously.
• Automatic events retry up to eight attempts over about 28 hours after a timeout or non-2xx response.
• Redirects are not followed; a 3xx counts as a failed attempt.
• A 410 Gone response disables the endpoint immediately.
• Continued failures trigger a warning after 24 hours and disable the endpoint after 72 hours. Events sent while disabled are not replayed.

Rotate the secret

Rotate an endpoint’s secret from Settings. The previous secret remains valid for 24 hours, and deliveries contain signatures for both active secrets during the overlap. The Standard Webhooks library accepts a match from either secret.

For local testing, expose your server through an HTTPS tunnel and use Send test event from the endpoint settings. Manual tests and redeliveries are attempted once rather than retried automatically.