API Reference

Webhooks

Receive real-time events from CleverSearch in your own systems.

Event Types

Subscribe to the events that match your workflow.

analysis.completed

Triggered when a URL or batch analysis finishes.

injection.ready

Generated content blocks are ready for retrieval.

sitemap.processed

Sitemap import has finished and pages are available.

Payload Example

All webhook payloads are delivered as JSON.

{
  "id": "evt_123",
  "type": "analysis.completed",
  "created_at": "2026-02-22T10:00:00Z",
  "data": {
    "analysis_id": "analysis_123",
    "url": "https://example.com"
  }
}

Signature Verification

Validate every webhook to ensure authenticity.

●Read the raw request body

●Compute the HMAC signature with your webhook secret

●Compare against the x-cleversearch-signature header

●Reject requests with mismatched signatures

import crypto from "crypto";

export function verifyWebhook(body: string, signature: string, secret: string) {
  const digest = crypto
    .createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(digest, "hex")
  );
}

Webhook Reliability

Reliable webhook ingestion keeps automations accurate and timely.

●Verify signatures and reject unsigned requests.

●Handle retries idempotently using event IDs.

●Queue processing so endpoint latency stays low.

●Track dead-letter events and replay failures quickly.

Execution Phases

Phase 1: Integration

Implement auth, request validation, and core endpoint flow.

Output: Stable API client with retries and typed payloads.

Phase 2: Automation

Add async handling and webhook-driven workflows.

Output: Background jobs connected to reliable event processing.

Phase 3: Hardening

Improve observability, rate-limit handling, and security.

Output: Production-ready monitoring and incident runbooks.

Common Mistakes

●Calling endpoints from client-side code with secret credentials.

●Ignoring 202/async patterns and assuming immediate completion.

●Missing idempotency in webhook consumers, causing duplicate actions.

●Retrying aggressively without backoff during rate limiting.

Success Metrics

Successful Request Rate

>= 99% for non-4xx requests

Indicates resilient client logic and error handling.

Webhook Processing Delay

< 60 seconds median end-to-end

Keeps downstream automation timely and useful.

Auth Error Frequency

< 1% of total calls

Confirms credential management is stable.