Webhooks

Webhooks let you receive HTTP notifications when specific events happen in your SEOJuice account. Use them to integrate SEOJuice with your own tools, dashboards, or automation workflows.

How Webhooks Work

1. You create a webhook endpoint in the SEOJuice dashboard
2. You select which events you want to be notified about
3. When an event occurs, SEOJuice sends an HTTP POST request to your endpoint URL
4. Your server processes the payload and responds with a 2xx status code

Creating a Webhook

1. Go to your website dashboard
2. Navigate to Settings → Webhooks
3. Click Create Webhook
4. Enter your endpoint URL (must be HTTPS)
5. Select the events you want to subscribe to
6. Click Save

SEOJuice generates a unique secret key for each webhook endpoint. Use this to verify that incoming requests are genuinely from SEOJuice.

Available Events

Event	When It Fires
Report completed	A new audit report has finished generating
Analysis finished	Website analysis/crawl has completed
Links generated	New internal links have been created
Accessibility issues detected	New accessibility issues found during crawl
Content gap identified	New content opportunities discovered
Competitors updated	Competitor analysis data has been refreshed

Verifying Webhook Signatures

Every webhook request includes an HMAC-SHA256 signature in the headers. Verify it to ensure the request is authentic:

import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

The webhook secret is displayed when you create the endpoint and can be viewed in your webhook settings.

Delivery & Retries

• SEOJuice expects your endpoint to respond with a 2xx status code within 30 seconds.
• If delivery fails, SEOJuice retries up to 3 times with exponential backoff:
  • 1st retry: after 1 minute
  • 2nd retry: after 5 minutes
  • 3rd retry: after 30 minutes
• After 3 failed attempts, the delivery is marked as failed.

Testing Webhooks

From the webhook detail page in the dashboard, you can:

• Send a test event — Triggers a sample payload to your endpoint
• View delivery history — See all past deliveries with status, response code, and timing
• Inspect payloads — Review the exact JSON sent for each delivery

Managing Webhooks

• Edit — Change the URL or subscribed events at any time
• Disable — Temporarily stop deliveries without deleting the endpoint
• Delete — Permanently remove the webhook endpoint

Best Practices

• Always verify the HMAC signature before processing webhook payloads
• Respond to webhooks quickly (within a few seconds) and process the payload asynchronously if needed
• Handle duplicate deliveries gracefully — use event IDs to deduplicate
• Monitor your webhook delivery history for failures and fix endpoint issues promptly