Webhooks

Overview

Webhooks let you receive HTTP POST notifications whenever something interesting happens in AEO Optima. Instead of polling the API to check for new snapshots or alerts, you register an endpoint and the platform pushes events to it as they occur.

Use webhooks to:

• Pipe alerts into Slack, Microsoft Teams, or PagerDuty
• Trigger your CI/CD pipeline when a content optimization is published
• Sync visibility scores into your data warehouse in real time
• Notify a chatbot or internal tool when a hallucination correction is approved
• Chain into IndexNow to push fresh URLs to crawlers automatically

Plan gate: Webhooks are available on Pro-SME (5 endpoints), Enterprise-Brand (20 endpoints), and Enterprise-Agency (50 endpoints) plans.

Supported events

Registering a webhook

1. Open Settings → Webhooks from the sidebar
2. Click Add endpoint
3. Enter:
   • URL — the HTTPS endpoint that will receive POSTs (must be public and reachable)
   • Events — pick which events to subscribe to (you can select multiple)
   • Description — a label for your own reference (e.g., "Slack alerts")
4. Click Save
5. The platform generates a signing secret — copy it now, you'll need it to verify incoming requests

Payload format

Every webhook delivery has the same envelope:

{
  "id": "evt_01HX2J3K4M5N6P7Q8R9S",
  "type": "alert.triggered",
  "created_at": "2026-04-07T14:23:00Z",
  "organization_id": "org_abc",
  "project_id": "prj_xyz",
  "data": {
    /* event-specific payload */
  }
}

The data field varies by event type. For example, an alert.triggered event includes the rule name, the metric that crossed the threshold, the current and previous values, and a deep link back into the platform.

Report events

report.generated carries the report's identity and its headline:

A schedule's own Webhook delivery channel posts report.delivered with the same aiBrandScore, letterGrade, insufficientData and scoreNotLoaded fields, plus projectName, reportType, frequency, totalSnapshots, reportUrl and historyId. A report that could not be generated at all sends neither event.

Verifying signatures

Every webhook request includes an X-AEO-Signature header of the form sha256=<hex> plus a companion X-AEO-Timestamp header (Unix seconds). The signature is an HMAC-SHA256 computed with your endpoint's signing secret over the string timestamp + "." + rawBody — not the body alone. Always verify this signature before trusting the payload — without verification, anyone who knows your URL can forge events.

Verification in pseudocode:

sig_header = request.headers["X-AEO-Signature"]   # e.g. "sha256=abc123..."
provided   = sig_header.removeprefix("sha256=")
ts         = request.headers["X-AEO-Timestamp"]
expected   = hmac_sha256(secret, ts + "." + request.body)   # hex digest
if not constant_time_equal(provided, expected):
    return 401

Use a constant-time comparison to avoid timing attacks. Most HMAC libraries provide this — for example, hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js. You may also reject deliveries whose X-AEO-Timestamp is too old, to limit replay.

Each delivery also carries X-AEO-Event (the event type) and X-AEO-Delivery (a unique delivery id) — use the latter to dedupe idempotently.

Delivery, retries, and timeouts

• Timeout: 10 seconds. If your endpoint doesn't respond in time, the delivery is marked failed.
• Retries: 3 attempts with backoff of 60s, 10min, then 1hr. After the third failure the delivery is dropped.
• Circuit breaker: If your endpoint fails 5 deliveries in a row, the platform automatically disables it and alerts you. Re-enable from the webhook settings page once you've fixed the issue.

The webhook settings page shows recent deliveries with status, timestamp, and the response your endpoint returned — useful for debugging.

Security

• Webhooks must use HTTPS. HTTP endpoints are rejected.
• Always verify the X-AEO-Signature header (see above)
• Rotate the signing secret periodically — the settings page has a Rotate secret button. After rotation, deliveries use the new secret immediately, so deploy the new secret to your endpoint first.
• Don't include the signing secret in URLs, query strings, or logs

Best practices

• Respond fast. Acknowledge the delivery (return 2xx) within a couple seconds, then process the payload asynchronously. If you do heavy work synchronously, you'll hit the 10-second timeout.
• Be idempotent. Each event has a unique id. If you receive the same id twice (from a retry), don't process it twice.
• Log raw deliveries. Save the raw payload and signature header. When debugging, you'll want to replay the exact bytes the platform sent.
• Subscribe to only the events you need. A webhook firing on every snapshot completion can be hundreds of POSTs per day on a busy project — only subscribe to high-volume events if you actually need them.
• Use the test button. The settings page has a "Send test event" button that delivers a synthetic payload to your endpoint. Use it to verify your endpoint and signature verification before relying on real events.

Related docs

• API Keys — alternative if you'd rather poll the API instead of receive pushes
• Alert Rules — most webhook subscribers care about this event
• IndexNow — chain webhooks into URL re-indexing