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.

What are webhooks?

Webhooks are automated messages sent from our servers to your application when specific events occur. Unlike traditional APIs where you poll for updates, webhooks push data to you instantly.

Real-time

Receive notifications instantly when events happen, no polling required.

Secure

All webhooks are signed and verified to ensure authenticity.

Reliable

Automatic retries ensure delivery even if your endpoint is temporarily unavailable.

Configurable

Choose which events you want to receive and configure multiple endpoints.

Setting up webhooks

Create an endpoint

Set up an HTTPS endpoint in your application that can receive POST requests. This endpoint should be publicly accessible and able to handle JSON payloads.

Requirements:

• Must accept POST requests
• Must use HTTPS (SSL/TLS)
• Should respond within 10 seconds
• Should return 2xx status codes for success

Configure webhook URL

In your dashboard, go to Settings → API → Webhooks and add your endpoint URL. You can configure multiple webhooks for different purposes.

Dashboard location:

Settings → API → Webhooks → Add Webhook

Select events

Choose which events you want to receive notifications for. You can subscribe to specific event types or receive all events.

Available events:

• audit.completed - Audit finished successfully
• audit.failed - Audit encountered an error
• audit.started - Audit began processing
• report.generated - Report is ready for download

Test your webhook

Use the test button in your dashboard to send a sample webhook payload to your endpoint. Verify that your application receives and processes the data correctly.

Test before going live

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

Webhook payload structure

Request headers

Content-Type: application/json

User-Agent: AISEOTurbo-Webhook/1.0

X-Webhook-Signature: sha256=abc123...

X-Webhook-ID: wh_1234567890

X-Webhook-Timestamp: 1640995200

Payload structure

{ "id": "wh_1234567890", "event": "audit.completed", "created": 1640995200, "data": { "audit_id": "audit_123", "url": "https://example.com", "status": "completed", "score": 85, "issues_found": 12, "report_url": "https://api.aiseoturbo.com/reports/audit_123" }, "account": { "id": "acc_123", "name": "Example Account" } }

Available webhook events

audit.started

Fired when an SEO audit begins processing.

Contains: audit_id, url, started_at

audit.completed

Fired when an SEO audit finishes successfully.

Contains: audit_id, url, score, issues_found, report_url, completed_at

audit.failed

Fired when an SEO audit encounters an error.

Contains: audit_id, url, error_message, error_code, failed_at

report.generated

Fired when a detailed report is generated and ready for download.

Contains: audit_id, report_id, report_url, format, generated_at

Security & verification

Webhook signatures

All webhooks include a cryptographic signature to verify authenticity. You should always verify the signature before processing webhook data.

How to verify signatures:

Get the signature from the X-Webhook-Signature header
Create a string with timestamp.payload
Compute HMAC-SHA256 using your webhook secret
Compare the computed signature with the received signature

Code example

// Node.js example

const crypto = require('crypto');

const signature = req.headers['x-webhook-signature'];

const timestamp = req.headers['x-webhook-timestamp'];

const payload = JSON.stringify(req.body);

const expectedSignature = crypto

.createHmac('sha256', WEBHOOK_SECRET)

.update(`${timestamp}.${payload}`)

.digest('hex');

Best practices

Always verify signatures

Implement signature verification to ensure webhooks are genuinely from our service.

Handle duplicates

Webhooks may be delivered multiple times. Use webhook IDs to handle duplicates gracefully.

Respond quickly

Your endpoint should respond within 10 seconds to avoid timeouts and retries.

Log webhook activity

Keep logs of received webhooks for debugging and audit purposes.

Troubleshooting

Common issues

Webhook not received

• Check that your endpoint is publicly accessible
• Verify the URL is correct in your webhook settings
• Ensure your server accepts POST requests
• Check firewall and security group settings

Signature verification fails

• Ensure you're using the correct webhook secret
• Check that you're including the timestamp in the signed payload
• Verify the payload is exactly as received (no modifications)

Timeout errors

• Respond to webhooks within 10 seconds
• Process webhook data asynchronously if needed
• Return a 2xx status code immediately after validation

Testing webhooks

Use tools like ngrok or webhook.site to test your webhook endpoint during development.

Testing tools:

• ngrok: Expose local servers to the internet
• webhook.site: Inspect webhook payloads online
• Postman: Test webhook endpoints manually
• Dashboard test button: Send test webhooks from your account

Need help with webhooks?

Having trouble setting up or troubleshooting webhooks? Our developer support team can help you get real-time notifications working in your application.

Contact Developer Support API Documentation Authentication Guide