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.

Supported Events

Event	Trigger	Payload Includes
job.completed	Content or publish job finishes successfully	job_id, keyword, s3_key, word_count, seo_score
job.failed	Job encounters an unrecoverable error	job_id, keyword, error_message
article.published	Article published to WordPress	post_id, url, title, keyword, publish_type
article.unpublished	Article reverted to draft by audit agent	post_id, url, reason
audit.completed	Site-wide SEO audit finishes	job_id, site_url, score, issues_count
rank.changed	Keyword position changes by 5+ positions	keyword, old_position, new_position, url

Configuration

Navigate to Settings → Webhooks

Click Add Webhook to create a new endpoint.

Enter Endpoint URL

Provide the HTTPS URL that will receive webhook payloads. Must be publicly accessible and respond with a 2xx status code within 10 seconds.

Select Events

Choose which events trigger this webhook. You can subscribe to all events or select specific ones.

Set Secret

Optionally set a signing secret. All webhook payloads include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, allowing you to verify authenticity.

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.

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)
  );
}

Common 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.

Use Case	Webhook Event	Integration Example
Slack notifications	job.completed, job.failed	Post a formatted message to a Slack channel with article title, keyword, and SEO score
Social media sharing	article.published	Queue published articles for sharing on Twitter, LinkedIn, or Facebook via Buffer API
CMS sync	article.published	Update a headless CMS or content distribution platform when new articles go live
Quality alerts	job.failed, article.unpublished	Send PagerDuty alerts when jobs fail or articles are unpublished due to low scores
Analytics tracking	job.completed	Log article creation events to your internal analytics system for reporting
Rank monitoring	rank.changed	Trigger content optimization when a keyword drops below a threshold position

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.

Design your endpoint to be idempotent — processing the same event twice should produce the same result. Use the event_id field in each payload for deduplication.

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.

1Start a tunnel — Run ngrok http 3000 to get a public URL that forwards to your local server on port 3000.
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).
3Trigger a test event — Create a test job or use the dashboard's "Send Test Webhook" button to generate a sample payload.
4Inspect the payload — Check your server logs to confirm the payload arrived, the signature validates, and your handler processes it correctly.

Tunnel URLs change every time you restart ngrok (on the free plan). Update your webhook endpoint in the dashboard after each restart, or use a paid ngrok plan for stable URLs.