MentionOwl API

Quick start

Create a named key under Profile → API Key. Choose read-only, site-management, or webhook-management access for the integration’s actual work. Keys expire, can be revoked independently, and are shown only once.

curl https://www.mentionowl.com/api/me \
  -H "Authorization: Bearer mo_live_your_key"

Successful requests return { "data": ... }. Errors return { "error": "..." }. Missing credentials use 401, invalid permissions or entitlements use 403, inaccessible resources use 404, conflicting transitions use 409, oversized or unsupported bodies use 413/415, limits use 429, and unexpected failures use 500.

Use a key with webhook access. The response includes a whsec_… signing secret once; store it in your secrets manager.

curl -X POST https://www.mentionowl.com/api/webhooks \
  -H "Authorization: Bearer mo_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "url": "https://example.com/webhooks/mentionowl",
    "events": ["site.created", "monitoring.completed"]
  }'

MentionOwl accepts public HTTPS destinations only. Every delivery is persisted, attempted immediately, retried up to three times, and carries a stable delivery ID for receiver-side deduplication.

Verify a webhook signature

Read the raw request body. Sign deliveryId.timestamp.rawBody with HMAC-SHA256, compare it to the hexadecimal value after v1=, reject old timestamps, and deduplicate the delivery ID.

import crypto from "node:crypto";

const deliveryId = req.headers["x-mentionowl-delivery"];
const timestamp = req.headers["x-mentionowl-timestamp"];
const received = req.headers["x-mentionowl-signature"];
if (typeof deliveryId !== "string" || typeof timestamp !== "string" ||
    typeof received !== "string") throw new Error("Missing webhook signature");

const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > 300) throw new Error("Stale webhook");

const signed = `${deliveryId}.${timestamp}.${rawBody}`;
const expected = "v1=" + crypto
  .createHmac("sha256", process.env.MENTIONOWL_WEBHOOK_SECRET)
  .update(signed)
  .digest("hex");

const valid = received.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));