Webhooks

Summary#

Metric Vault receives one inbound webhook, from Stripe, which is what keeps plan entitlements in step with subscriptions. It sends two kinds of outbound webhook, both belonging to the alerting features: a formatted Slack message and a generic JSON payload you can point at any HTTPS endpoint. There are no webhooks for tool completion, and the public API is synchronous, so nothing calls you back after an /api/v1/analyze request.

Overview#

Inbound: the Stripe webhook#

Endpoint#

Signature verification#

The signature is computed over the string <timestamp>.<raw body> using the webhook signing secret, then compared in constant time against the v1= values in the stripe-signature header. Events older than 300 seconds are rejected as replays.

Handled events#

A subscription is treated as entitling when its status is active, trialing or past_due. Keeping past_due deliberately preserves access during dunning rather than cutting a paying customer off on the first failed charge. See Subscription states and Failed payments.

Responses#

Safety property#

Subscription events write the plan only when the existing record was itself set by Stripe. A manually granted or comped plan is never overwritten by an incoming webhook, so a support-issued upgrade survives billing traffic.

The reconciliation backstop#

Webhooks can be missed. POST /api/billing/sync pages through live Stripe subscriptions and reconciles stored plans against them. It also runs as the billing_sync background job, so entitlements self-heal within a scheduling cycle even if a webhook never arrives. It grants freely but only revokes when it has completed a full scan, and it only ever revokes records that Stripe set. See Internal endpoints.

Outbound: alert webhooks#

Two features send outbound webhooks: Competitor Monitor and rank alerts. Both use the same dispatcher, so the payloads are identical in shape.

Where they are configured#

All three channels are optional and independent. Supplying none means the change is recorded in the app and appears in the notifications feed, but nothing is pushed anywhere.

The severity gate#

Each monitored URL carries a min_severity of Low, Medium or High. Changes below that level are recorded but never dispatched. Rank alerts always dispatch at Low, so every rank drop that passes the drop threshold is sent.

Slack payload#

Sent as POST with Content-Type: application/json to your Slack incoming webhook URL. It uses Slack's Block Kit format: a header block reading Watchtower alert, a section naming the monitored label and linking the URL, a section listing up to 8 changes as • *Severity* — description with an …and N more line when there are more, and a context line showing the severity gate, the check interval, and a link back to Competitor Monitor.

The fallback text field reads *Watchtower* — change detected on <label>.

Generic JSON payload#

Sent as POST with Content-Type: application/json to your endpoint. This is the one to point at Zapier, Make, or your own service.

{
  "source": "Metric Vault Watchtower",
  "event": "changes_detected",
  "monitored": {
    "id": 128,
    "url": "https://competitor.example.com/pricing",
    "label": "Competitor pricing page",
    "competitor_domain": "competitor.example.com"
  },
  "changes": [
    {
      "severity": "High",
      "change_type": "price_drop",
      "description": "Pro plan price fell from $99 to $79",
      "old_value": "99",
      "new_value": "79",
      "numeric_delta": -20
    }
  ],
  "top_change": {
    "severity": "High",
    "description": "Pro plan price fell from $99 to $79"
  },
  "change_count": 1,
  "detected_at": "2026-08-06T09:15:00.000Z",
  "dashboard_url": "https://metricvaultai.com/dashboard#competitor-monitor"
}

Rank-alert specifics#

A rank alert fires when the position drops by at least the alert's threshold (1 to 20, default 5) or when a keyword that was in the top 10 leaves it. The change carries:

Enabled rank alerts are re-checked roughly every 24 hours.

Email channel#

If an address is set and email sending is configured, an HTML message is sent from Watchtower <alerts@metricvaultai.com> with the subject Watchtower: <N> change(s) on <label>, listing up to 12 changes.

Delivery semantics#

These are the properties that matter when you build a receiver:

Testing a webhook#

POST /api/monitor/test-alert dispatches a synthetic price_drop change at High severity to whichever channels you supply in the body, with the description Test alert — your alert channels are wired correctly. It does not require an existing monitored URL and does not cost credits.

Other callback-shaped mechanisms#

These are not webhooks in the usual sense, but they are HTTP callbacks and it helps to know they exist.

What does not exist#

Being explicit saves an integration built on a wrong assumption:

• No webhooks for tool completion. Running a tool does not call you back. The dashboard tools are request-response, including long article jobs.
• No webhooks for the public API. POST /api/v1/analyze returns its result in the response.
• No subscription-management API for webhooks. Outbound endpoints are configured per monitored URL or per rank alert, not through a webhook registry.
• No signing secret or signature header on outbound payloads.
• No delivery history, retry queue or dead-letter view.
• No webhooks for billing, usage or team events.