API Reference

curl -X GET "http://127.0.0.1:37837/api/v1/rest/conversations?limit=25" \
  -H "Authorization: Bearer mt_your_api_token"

Generate tokens in Settings -> REST API -> API Tokens. Tokens are shown once and should be stored securely. You can later edit a token's name, description and scopes without changing the token string. Webhook destinations are configured separately under Settings -> REST API -> Webhook subscriptions — see the Webhooks section below.

X-Webhook-Signature: sha256=<hmac_sha256_of_raw_body>
X-Webhook-Event: conversation.completed
X-Webhook-Delivery-Id: <delivery_uuid>
X-Webhook-Timestamp: <unix_timestamp_seconds>

X-Webhook-Delivery-Id is stable across retries for the same delivery. Use it for idempotency. X-Webhook-Timestamp is refreshed on every attempt (including retries) so replay protection works on retries too.

1. Read the raw request body before any JSON parsing.
2. Compute expected = HMAC_SHA256(subscription_webhook_secret, raw_body) using the signing secret of the subscription that received the delivery (matched via _meta.subscription_id).
3. Compare expected against the hex value in X-Webhook-Signature using a constant-time comparison (for example hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js).
4. Reject the request when |now_unix_seconds - X-Webhook-Timestamp| > 300 (5 minute replay window). We never deliver payloads older than this; anything past 5 minutes is treated as a replay.
5. Treat repeated X-Webhook-Delivery-Id values as the same delivery and skip re-processing.

import crypto from "node:crypto";

function verifyMeetricWebhook(req, secret) {
  const rawBody = req.rawBody; // Buffer or string captured BEFORE JSON parsing
  const sigHeader = req.headers["x-webhook-signature"] || "";
  const tsHeader = Number(req.headers["x-webhook-timestamp"] || "0");

  // 1) Replay window: 5 minutes
  if (Math.abs(Math.floor(Date.now() / 1000) - tsHeader) > 300) {
    return { ok: false, reason: "replay_window_exceeded" };
  }

  // 2) HMAC-SHA256 of the raw body
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  // 3) Constant-time compare
  const sigBuf = Buffer.from(sigHeader);
  const expBuf = Buffer.from(expected);
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return { ok: false, reason: "bad_signature" };
  }

  return { ok: true };
}

Meetric retries failed deliveries with exponential backoff using the same X-Webhook-Delivery-Id. Schedule:

• Attempt 1: immediate
• Attempt 2: ~1 minute later
• Attempt 3: ~5 minutes later
• Attempt 4: ~30 minutes later
• Attempt 5: ~2 hours later
• Attempt 6: ~12 hours later (final)

We consider a delivery successful when your endpoint returns a 2xx status code within 10 seconds. Use GET /rest/webhooks/deliveries to inspect recent attempts (last 7 days) across all subscriptions for your account; each row includes subscription_id, and you can filter the list by ?subscription_id=<uuid> for a per-destination view.

• subscription_id — canonical correlation key. Always present. Matches the subscription you configured in Settings -> REST API -> Webhook subscriptions.
• delivery_id — same value as the X-Webhook-Delivery-Id header. Stable across retries.
• content_ready — object of booleans describing which conversation parts were present when this delivery was built. Use it to distinguish "empty / not applicable" from "not ready yet" instead of re-fetching over REST.
  • transcript / summary — always true on a delivered conversation.completed event. The webhook is not enqueued until both are ready.
  • insights / recording — may be false on a delivered event. Insights and recordings are best-effort and do not block delivery — false means that part was not present (or not in scope), not that the event was sent too early.
• token_prefix — DEPRECATED. Retained for one minor version so existing integrations that read _meta.token_prefix keep working. Set to the prefix of a same-account API token that has the same webhook URL when one exists, otherwise null. Use subscription_id instead. This field is removed in a future release.

Pressing Test on a webhook subscription sends a test delivery. It carries a sample conversation in the same shape as conversation.completed, filtered by the subscription scopes, so you can test your integration before you have any real conversations. Test deliveries are listed in the delivery log like any other delivery. On test rows in the delivery list, resource_id is the delivery id, not a conversation id.

{
  "event": "webhook.test",
  "data": {
    "message": "This is a test webhook delivery",
    "subscription_name": "<subscription name>",
    "conversation": {
      "id": "00000000-0000-4000-8000-000000000000",
      "...": "same fields as conversation.completed"
    }
  },
  "_meta": { "subscription_id": "<uuid>", "delivery_id": "<uuid>", "test": true }
}

• The sample conversation always has the id 00000000-0000-4000-8000-000000000000 and never resolves to a real conversation.
• Always check event / X-Webhook-Event before processing data.conversation. Only conversation.completed describes a real conversation.
• Requesting a notetaker returns conversation_id as null, because the conversation is created only after the meeting ends and is processed. Use the id from the conversation.completed webhook to fetch it.

{
  "requests_per_minute": 60,
  "daily_conversation_quota": 10000
}

Limits are configured per token. Daily quota counts unique conversations accessed per day. When the per-minute limit is exceeded, the response includes a Retry-After header (seconds) — honor it instead of retrying immediately.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "details": { "retry_after_seconds": 60 },
  "retry_after_seconds": 60
}

Documented error responses on /rest/* use the same envelope when applicable. Branch on a published stable code field; treat message as human-readable text that may change between releases.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Token is missing required scope: transcripts",
  "code": "missing_scope",
  "details": { "required_scope": "transcripts" }
}

• 200 - request succeeded
• 400 - invalid parameters or body
• 401 - token missing, invalid, inactive, revoked, or expired
• 403 - scope missing, recordings not enabled, or daily quota reached
• 404 - resource not found in this account / not visible to this token
• 429 - per-minute rate limit exceeded (honor Retry-After)
• 500 - unexpected internal error; details are sanitized
• 502 - an upstream dependency returned a failing or invalid response
• 503 - a required service is temporarily unavailable
• 504 - an upstream or database request timed out

The code field uses these stable identifiers. Use them for retry/branching logic instead of matching on the message.