Real-time notifications

Webhooks allow you to receive real-time notifications when events occur in your account. Get instant updates about audit completions, errors, and other important events without polling the API.

What are webhooks?

Webhook Basics

Webhooks are automated messages sent from our servers to your application when specific events occur. Instead of constantly checking for updates via API calls, webhooks push data to your endpoints instantly.

Traditional Polling

• Check API every few minutes

• Wasteful API calls

• Delayed notifications

• Server load

Webhooks

• Instant notifications

• No unnecessary API calls

• Real-time updates

• Efficient resource usage

Setting up webhooks

Create webhook endpoint

Build an HTTPS endpoint in your application that can receive POST requests. This endpoint should be able to handle JSON payloads and return appropriate HTTP status codes.

Requirements: HTTPS, POST method, JSON handling, 200 status response

Configure webhook URL

In your dashboard, go to API settings and add your webhook endpoint URL. You can configure multiple webhooks for different events or environments.

Dashboard: Settings → API → Webhooks → Add Webhook

Select events

Choose which events you want to receive notifications for. You can subscribe to all events or select specific ones like audit completions, errors, or billing updates.

audit.completed

audit.failed

billing.payment

account.updated

Test your webhook

Use our webhook testing tool to send test events to your endpoint. Verify that your application correctly receives and processes the webhook data.

Test before going live

Always test your webhook endpoint with sample data before enabling it for production events.

Available webhook events

audit.completed

Fired when an SEO audit finishes successfully. Includes audit results and metadata.

Contains: audit_id, status, results_url, completed_at

audit.failed

Fired when an SEO audit fails or encounters an error. Includes error details and retry information.

Contains: audit_id, error_message, error_code, retry_count

audit.started

Fired when an SEO audit begins processing. Useful for tracking audit queue status.

Contains: audit_id, started_at, estimated_completion

billing.payment_succeeded

Fired when a payment is successfully processed. Includes invoice details and billing information.

Contains: invoice_id, amount, currency, payment_method

billing.payment_failed

Fired when a payment attempt fails. Includes failure reason and retry information.

Contains: invoice_id, failure_reason, next_retry_date

Webhook payload format

All webhooks send JSON payloads with this structure:

{
  "event": "audit.completed",
  "id": "wh_1234567890",
  "timestamp": "2025-03-15T10:30:00Z",
  "data": {
    "audit_id": "audit_abc123",
    "status": "completed",
    "results_url": "https://api.aiseoturbo.com/v1/audits/audit_abc123/results",
    "completed_at": "2025-03-15T10:29:45Z",
    "metadata": {
      "url": "https://example.com",
      "crawl_depth": 2,
      "user_agent": "AISEO Turbo Crawler"
    }
  }
}

Common Fields

event - Event type identifier
id - Unique webhook ID
timestamp - ISO 8601 timestamp
data - Event-specific payload

Headers

Content-Type - application/json
User-Agent - AISEO Turbo Webhook
X-Webhook-ID - Webhook identifier
X-Signature - Request signature

Security & verification

Request Signatures

All webhook requests include a cryptographic signature in the X-Signature header. Verify this signature to ensure the request comes from our servers.

HTTPS Only

Webhooks are only sent to HTTPS endpoints. HTTP endpoints are not supported for security reasons.

Retry Logic

Failed webhook deliveries are automatically retried with exponential backoff for up to 24 hours.

Idempotency

Each webhook event has a unique ID. Use this to prevent processing duplicate events.

Handling webhook requests

Best practices for webhook endpoints:

Respond Quickly

Return a 200 status code immediately. Process the webhook asynchronously to avoid timeouts.

Verify Signatures

Always verify the webhook signature before processing to prevent spoofing attacks.

Handle Duplicates

Use the webhook ID to detect and ignore duplicate events that may be retried.

Log Everything

Log all webhook requests for debugging and audit purposes.

Testing webhooks

Test your webhook setup

Use our webhook testing tools to ensure your endpoint is working correctly before enabling live webhooks.

Webhook Tester

Send test events to your endpoint directly from the dashboard. View delivery status and response codes.

Sample Payloads

Use our documentation to get sample webhook payloads for testing your parsing logic.

Request Inspector

Inspect the headers, signatures, and payloads of test webhook requests.

Troubleshooting

Webhook Not Received

• Check endpoint URL is correct
• Verify HTTPS is enabled
• Ensure server is responding
• Check firewall settings
• Review webhook logs

Signature Verification Failed

• Verify webhook secret key
• Check signature algorithm
• Ensure raw request body
• Compare expected vs received
• Check timestamp validity

Need help with webhooks?

Having trouble setting up or troubleshooting webhooks? Our developer support team can help you get everything working.

Contact Developer Support View All API Articles