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/webhookswithurl(HTTPS only),event_typesand an optionaldescription. The response holds the signingsecret, shown only this once.GET /v1/webhooks,GET /v1/webhooks/{id},PATCH /v1/webhooks/{id}(to change the URL or events, or setenabled), andDELETE /v1/webhooks/{id}.POST /v1/webhooks/{id}/rotate-secretreplaces the secret at once.POST /v1/webhooks/{id}/testsends a test event.GET /v1/webhooks/{id}/deliverieslists the last 50 deliveries, andPOST /v1/webhooks/{id}/deliveries/{delivery_id}/replaysends 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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdv1 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.