# 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:

```json
{
  "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:

```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:

```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.
