Set up webhooks

Webhooks are how SEMOptimiser tells your systems that something happened. Instead of polling our API every minute to check for new audit results, you give us a URL and we POST to it the moment the event fires. They're available on Management and CEO plans.

Supported events

Create a webhook

1. Go to Settings → Webhooks.
2. Click New webhook.
3. Enter the destination URL. Must be HTTPS in production (we accept HTTP only for localhost during testing).
4. Tick the events you want to receive. You can pick all or a subset.
5. Optionally add a secret. We'll sign every payload with HMAC-SHA256 using this secret so you can verify the request actually came from us.
6. Save.

Payload format

Every webhook is a POST with a JSON body and a few standard headers.

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-27T10:00:00Z",
  "data": {
    "audit_id": "aud_42",
    "site_id": "site_1",
    "url": "https://example.com",
    "score": 87,
    "issues": { "critical": 3, "warning": 12, "info": 28 }
  }
}

Verify the signature

The X-SEMO-Signature header contains a timestamp and a v1 signature. To verify:

1. Extract the timestamp t and signature v1 from the header.
2. Concatenate: t + "." + raw_request_body.
3. Compute HMAC-SHA256 of that string using your webhook secret.
4. Compare your computed hash to v1. They should match exactly.
5. Reject the request if the timestamp is older than 5 minutes (replay protection).

Retries and delivery guarantees

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

Inspecting recent deliveries

Settings → Webhooks → [your webhook] → Deliveries shows the last 100 attempts: timestamp, event type, your response code, response time. Click any to see the exact payload we sent and the exact response we got back – invaluable for debugging.

Disable temporarily

Each webhook has a toggle. Disable it during planned maintenance so we don't spam your endpoint with retries while you're down.