SEO Webhook Setup

Webhooks let you receive push notifications when events occur in your AI SEO Agents account. Instead of polling the API, your server receives an HTTP POST request with the event payload the moment something happens. Our webhook system follows the CloudEvents specification for event envelope formatting and draws on best practices from GitHub's webhook architecture. Across our platform, webhooks deliver over 50,000 events per month with a 99.7% first-attempt success rate.

Supported Events

SEO Webhook Configuration

Payload Format

{
  "event": "job.completed",
  "timestamp": "2026-02-26T14:30:00Z",
  "data": {
    "job_id": "content-a1b2c3d4",
    "keyword": "trade show booth design",
    "s3_key": "articles/agent-xyz/trade-show-booth-design.md",
    "word_count": 2450,
    "seo_score": 87
  }
}

Verifying Webhook Signatures

If you configured a signing secret, verify each request to ensure it came from AI SEO Agents:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Policy

Failed webhook deliveries (non-2xx response or timeout) are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 5 failed attempts, the webhook is marked as unhealthy and delivery is paused. You'll receive an email notification and can re-enable it from the Settings page.

Delivery Guarantees

AI SEO Agents provides at-least-once delivery for all webhook events. This means every event is guaranteed to be delivered to your endpoint at least once, but under certain conditions (network timeouts, retry storms) the same event may be delivered more than once. Your endpoint must handle duplicate deliveries gracefully.

• Idempotency requirement — Use the event_id field (included in every payload) as a deduplication key. Store processed event IDs in a database or cache with a TTL of at least 24 hours. Before processing any event, check if its event_id has already been handled.
• Ordering is not guaranteed — Events may arrive out of order, especially during retry scenarios. If your workflow depends on event ordering (e.g., job.completed must follow job.started), use the timestamp field to reconcile ordering on your side.
• Delivery latency — Under normal conditions, events are delivered within 2 seconds of occurring. During peak traffic, latency may increase to 5-10 seconds. Retried events follow the backoff schedule described above.

Why Signature Verification Matters

Without signature verification, your webhook endpoint is vulnerable to two critical attack vectors that have affected production systems in the SEO industry:

• Replay attacks — An attacker intercepts a legitimate webhook payload and replays it to your endpoint, potentially triggering duplicate actions (publishing the same article twice, sending duplicate Slack notifications). Signature verification combined with timestamp validation (reject events older than 5 minutes) prevents this.
• Spoofed payloads — An attacker sends fabricated webhook payloads to your endpoint, injecting fake data into your system. Without signature verification, your endpoint has no way to distinguish legitimate events from forgeries. Always verify the X-Webhook-Signature header using your signing secret before processing any payload.

Advanced Security Practices

Beyond signature verification, there are several best practices for hardening your webhook endpoint against abuse and ensuring reliable event processing in production deployments handling sensitive SEO data.

• IP allowlisting: Restrict your webhook endpoint to accept requests only from AI SEO Agents IP ranges. Contact support for the current list of egress IP addresses used by the delivery system.
• TLS enforcement: Webhook URLs must use HTTPS. The platform validates the TLS certificate on your endpoint and will not deliver events to endpoints with expired, self-signed, or invalid certificates.
• Idempotent processing: Design your endpoint to handle duplicate deliveries gracefully. Each webhook payload includes a unique event_id for deduplication. Store processed event IDs with a TTL of at least 24 hours.
• Rate limiting: While the platform limits delivery to one event per second per endpoint under normal conditions, bursts can occur when multiple jobs complete simultaneously. Implement rate limiting on your endpoint to prevent overload.

// Node.js signature verification example
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  const expectedSig = `sha256=${expected}`;
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig),
    Buffer.from(signature)
  );
}

SEO Webhook Use Cases

Webhooks enable a wide range of automation workflows that extend the platform's capabilities beyond the built-in dashboard. Here are popular integrations our customers have built. Each use case can be implemented with minimal code because the webhook payload includes all the contextual data needed to take action — no additional API calls are required in most scenarios. For agencies managing multiple client sites, webhooks provide a centralized way to monitor all content operations across your entire portfolio from a single integration point.

Debugging Webhooks

When webhook deliveries fail or your endpoint behaves unexpectedly, several tools and techniques help diagnose the problem. The webhook delivery log in Settings provides visibility into every attempt.

• Delivery log: Navigate to Settings > Webhooks and click on a webhook endpoint to view its delivery history. Each entry shows event type, delivery timestamp, HTTP response code, and response body.
• Test endpoint: Use the "Send Test" button to send a sample event to your endpoint. Test events include a "test": true field so your endpoint can distinguish them from production events.
• Request inspection: During development, point your webhook URL at webhook.site or requestbin.com to view the full request headers and body without building a server.
• Local development: Use ngrok or Cloudflare Tunnel to expose your local development server for webhook testing.
• Timeout debugging: Deliveries require a response within 10 seconds. If processing takes longer, respond with 202 (Accepted) immediately and process asynchronously.

Webhook Payload Reference

Every webhook payload follows a consistent envelope format with the event type, timestamp, and a data object containing event-specific fields. All timestamps use ISO 8601 format (UTC). The event_id is a unique identifier for each delivery that enables reliable deduplication and tracing across distributed systems. The payload format is designed to be self-contained — your webhook handler should have all the information it needs to take action without making additional API calls to the platform. This design principle ensures that webhook integrations remain functional even during brief periods of API unavailability or rate limiting.

// article.published payload example
{
  "event_id": "evt_a1b2c3d4e5f6",
  "event": "article.published",
  "timestamp": "2026-02-26T14:45:00Z",
  "data": {
    "post_id": 2603,
    "url": "https://example.com/trade-show-booth-cost/",
    "title": "Trade Show Booth Cost: Complete Guide for 2026",
    "keyword": "trade show booth cost",
    "publish_type": "elementor_publish",
    "seo_score": 89,
    "word_count": 2454,
    "agent_id": "agent-a1b2c3d4",
    "job_id": "publisher-20260226-143000"
  }
}

For all event types and data fields, see the API Reference. For webhook transport security, review the Security Overview.

Testing Webhooks in Development

Before deploying webhooks to production, test your endpoint thoroughly in a development environment. Use a tool like ngrok or localtunnel to expose your local server to the internet so the platform can deliver webhook payloads to your development machine. This lets you inspect payloads, verify signature validation, and test error handling without deploying your webhook handler to a production server.

1. 1Start a tunnel — Run ngrok http 3000 to get a public URL that forwards to your local server on port 3000.
2. 2Register the tunnel URL — Set the ngrok URL as your webhook endpoint in the dashboard. Remember to include the full path (e.g., https://abc123.ngrok.io/webhooks/seo-agent).
3. 3Trigger a test event — Create a test job or use the dashboard's "Send Test Webhook" button to generate a sample payload.
4. 4Inspect the payload — Check your server logs to confirm the payload arrived, the signature validates, and your handler processes it correctly.

Webhooks vs Polling vs Event Streaming

Choosing the right event delivery mechanism depends on your latency requirements, infrastructure complexity, and scale. Here is how the three approaches compare for SEO platform integrations:

For most production integrations, we recommend webhooks as the default. They provide the best balance of simplicity, reliability, and efficiency. Use WebSocket streaming only when you need sub-second updates in an interactive UI. Use polling only when your infrastructure cannot accept inbound HTTPS connections.

Production Monitoring

Monitoring webhook delivery health is critical for production deployments. A failing webhook endpoint can silently break your automation pipeline, leading to missed notifications and stale data. Based on patterns from agencies managing 50+ client sites, we recommend tracking these metrics:

• Delivery success rate — Track the percentage of webhook deliveries that receive a 2xx response on the first attempt. A healthy endpoint maintains 99%+ success rate. Sustained drops below 95% indicate endpoint performance issues.
• Average response time — Your endpoint should respond within 2 seconds. Responses approaching the 10-second timeout indicate that your handler is doing too much synchronous processing — switch to async processing with an immediate 202 response.
• Retry volume — Monitor how many events require retries. A sudden spike in retries often indicates an endpoint outage or a deployment that introduced a bug in your webhook handler.
• Event gap detection — Track expected event sequences (e.g., every job.completed should follow a POST /jobs request). Missing events may indicate a configuration issue where the event type is not subscribed.

Related Documentation

• API Reference — Full API documentation for polling-based integration.
• Security Overview — Signature verification and transport security.
• Google Search Console — Set up Search Console integration for webhook-triggered reports.
• Pricing — Compare plans and webhook limits per tier.