Webhooks

#Configuration

Webhooks are configured per-brand. The dashboard UI lives in Content → Webhook settings:

• webhook_url — your endpoint
• webhook_secret — sent with every delivery so your endpoint can verify the sender (recommended)
• is_active — toggle without deleting

Programmatic access: GET/PUT /api/content/webhook-config/{brand} (session auth).

#Payload format

When a user (or a bulk action) sends an opportunity to your workflow, AnswerixAI POSTs JSON:

{
  "event": "opportunity.sent",
  "opportunity": {
    "id": "uuid",
    "title": "string",
    "description": "string",
    "type": "owned | earned",
    "impact": "high | medium | low",
    "opportunity_score": 87.5
  },
  "prompt": { "text": "string", "category": "string" },
  "data": { "...full source data (volume, gap %, keywords, competitors)..." },
  "brief": { "...full brief object, null if not generated yet..." },
  "brand": { "name": "Acme Corp", "domain": "acme.com", "industry": "SaaS" },
  "callback_url": "https://your-answerix-host/api/content/{id}/status"
}

The callback_url lets your workflow report back — PATCH it with a new status (e.g. done) when the article ships.

#Verifying the sender

If webhook_secret is set, every delivery carries it in a header:

X-Webhook-Secret: <your secret>

Reject any request where the header is missing or doesn't match. Use a long random value (openssl rand -hex 32) and treat it like a password.

#Delivery semantics

• Requests time out after 15 seconds.
• The response status and the first 1,000 characters of the response body are stored on the opportunity (webhook_response) and shown in the dashboard, so you can debug failed deliveries without server logs.
• A delivered opportunity moves to status sent with a webhook_sent_at timestamp.
• Failed deliveries aren't retried automatically — resend manually from the dashboard (single or bulk).

#Testing

The Content → Webhook settings page includes a Test webhook button that fires a synthetic payload:

{
  "event": "webhook.test",
  "message": "This is a test webhook from AEO platform.",
  "timestamp": "2026-07-15T10:00:00+00:00"
}

so you can validate your endpoint (including the X-Webhook-Secret header) before going live.

#Inbound webhooks

AnswerixAI also receives one webhook: POST /cloro/callback, where the Cloro scraping backend delivers AI-engine results. It's verified with an HMAC-SHA256 signature (CLORO_WEBHOOK_SECRET) and a 5-minute timestamp tolerance — you only need to care about it when self-hosting behind a firewall: the URL must be reachable from Cloro, or leave CLORO_WEBHOOK_URL unset to use inline polling instead.

Need help? See the FAQ.