Perspective API shuts down on December 31, 2026.Switch by changing one URL

Webhooks

Webhooks send events to your own HTTPS endpoint as they happen, so you can act on blocked messages, reviews and usage without polling. Payloads never include message text.

Events

Event When it fires
check.blocked A check's action is block.
check.review A check's action is review.
check.reviewed Someone allowed or blocked a check from the Review queue or MCP.
check.feedback A check was corrected to spam or not_spam.
usage.threshold_reached The team used 80% of its daily or monthly quota. Once per period.
usage.quota_exceeded The team used all of its daily or monthly quota. Once per period.
usage.overage_cap_reached Pay-as-you-go reached its cap. Once per period.
spam_wave.detected Blocked checks in 10 minutes are far above normal. At most hourly.
api_key.created An API key was created.
api_key.revoked An API key was revoked.

"Send test event" sends a webhook.test event to one endpoint, whatever it subscribes to.

Every event has the same envelope:

{
  "id": "6c1f2a8e-4b0d-4c55-9a31-5d1d1e7f2b10",
  "type": "check.blocked",
  "created_at": "2026-11-14T12:00:00.000Z",
  "data": {
    "check_id": "8f6f1c9e-0f0e-4c55-9a31-5d1d1e7f2b10",
    "action": "block",
    "spam": {
      "score": 0.97,
      "category": "scam",
      "reasons": ["Looks like a scam"]
    },
    "content_type": "message",
    "source": "api",
    "test": false,
    "created_at": "2026-11-14T12:00:00.000Z"
  }
}

When a check also asked for toxicity, self_harm, sexual or pii, check.blocked and check.review include each one's score, such as "pii": { "score": 0.97 }. Labels and personal-detail matches are left out, so a payload never carries message text.

Use the event's id to ignore an event you have already handled: a delivery can arrive more than once.

Endpoints

  • POST /v1/webhooks with url (HTTPS only), event_types and an optional description. The response holds the signing secret, shown only this once.
  • GET /v1/webhooks, GET /v1/webhooks/{id}, PATCH /v1/webhooks/{id} (to change the URL or events, or set enabled), and DELETE /v1/webhooks/{id}.
  • POST /v1/webhooks/{id}/rotate-secret replaces the secret at once.
  • POST /v1/webhooks/{id}/test sends a test event.
  • GET /v1/webhooks/{id}/deliveries lists the last 50 deliveries, and POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay sends one again with a fresh signature.

Endpoints must be reachable on the internet: private, loopback and link-local addresses are refused. Each plan allows a number of endpoints: 1 on Free, 5 on Pro and 20 on Scale.

Verify the signature

Every delivery has a spamgone-signature header:

spamgone-signature: t=1763121600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is the HMAC-SHA256, in hex, of the timestamp, a dot and the raw request body, made with your endpoint's secret. Check it against the raw body, before parsing the JSON, and reject deliveries older than 5 minutes.

Node.js:

const { createHmac, timingSafeEqual } = require("node:crypto");

const TOLERANCE_SECONDS = 5 * 60;

function verifySpamgoneSignature(secret, header, rawBody) {
  const parts = Object.fromEntries(
    (header ?? "").split(",").map((part) => part.trim().split("=")),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest();
  const actual = Buffer.from(parts.v1, "hex");
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

Python:

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_spamgone_signature(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(part.strip().split("=", 1) for part in (header or "").split(","))
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Retries

Answer with any 2xx within 10 seconds. Anything else, or no answer, is retried with growing waits (30 seconds, 2 minutes, 10 minutes, 30 minutes, then hourly up to 8 hours) for up to 24 hours after the event. If every delivery to an endpoint fails for 3 days, we turn the endpoint off and email the team's admins. Turn it back on from the dashboard, and replay the deliveries you need.

Deliveries don't follow redirects, so use the endpoint's final URL.