Webhooks: rank changes and audit events

Webhooks push events to your endpoint instead of you polling our API. Available on Management+. This page documents the event catalog, the signed-payload format, and retry semantics.

Event catalog

Create a webhook

1. Settings → Webhooks → New webhook.
2. Destination URL (must be HTTPS in production).
3. Tick events to subscribe.
4. Optionally add a secret (we'll sign every payload with HMAC-SHA256 using it).
5. Save.

Request format

http
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SEMOptimiser-Webhook/1.0
X-SEMO-Event: audit.complete
X-SEMO-Delivery: 7f3b...
X-SEMO-Signature: t=1717000000,v1=abc123def...

{
  "event": "audit.complete",
  "occurred_at": "2026-05-30T10:00:00Z",
  "data": {
    "audit_id": "aud_42",
    "site_id": "site_1",
    "url": "https://example.com",
    "score": 87,
    "issues": { "critical": 3, "warning": 12, "info": 28 }
  }
}

Signature verification

If you set a secret, every payload has an X-SEMO-Signature header. To verify:

1. Extract timestamp `t` and signature `v1` from the header.
2. Concatenate: `t + "." + raw_request_body`.
3. Compute HMAC-SHA256 of that string using your secret.
4. Compare to v1 using constant-time comparison.
5. Reject the request if the timestamp is older than 5 minutes (replay protection).

javascript
import crypto from 'crypto'

function verify(req, secret) {
  const [tPart, v1Part] = req.headers['x-semo-signature'].split(',')
  const t  = tPart.split('=')[1]
  const v1 = v1Part.split('=')[1]
  if (Math.abs(Date.now()/1000 - parseInt(t)) > 300) return false
  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.${req.rawBody}`).digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(v1, 'hex'))
}

Retry policy

We expect 2xx within 10s. If we don't get one, we retry with exponential backoff up to 8 times over 24 hours: 30s, 2m, 10m, 30m, 2h, 6h, 12h, 24h. After the 8th failure we mark delivery as permanently failed and email you.

Inspect deliveries

Settings → Webhooks → [your webhook] → Deliveries shows the last 100 attempts with timestamp, event, response code, response time, and the exact payload+response. Replay individual deliveries during debugging.