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 Professional (5 endpoints) and Enterprise (20 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.

Verifying signatures

Every webhook request includes an X-AEO-Signature header containing an HMAC-SHA256 of the request body, computed with your endpoint's signing secret. Always verify this signature before trusting the payload — without verification, anyone who knows your URL can forge events.

Verification in pseudocode:

signature = request.headers["X-AEO-Signature"]
expected = hmac_sha256(secret, request.body)
if not constant_time_equal(signature, 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.

Delivery, retries, and timeouts

• Timeout: 10 seconds. If your endpoint doesn't respond in time, the delivery is marked failed.
• Retries: 3 attempts with exponential backoff (1s, 4s, 16s). 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