Webhook Integration Guide: Automating Your Prediction Pipeline

Webhooks let you receive SykikAI predictions in real time without polling the API. When new predictions are published, a POST request is sent directly to your endpoint with the full prediction data. This is the preferred integration method for applications that need immediate updates.

How Webhooks Work

The flow is straightforward:

1. You register a webhook endpoint URL in your SykikAI dashboard
2. When predictions are published, our system sends a POST request to your URL
3. Your endpoint receives the payload, verifies the signature, and processes the data
4. You return a 2xx status code to confirm receipt

Configuring Your Endpoint

Your webhook endpoint must be publicly accessible over HTTPS. In your SykikAI dashboard, navigate to Webhook Settings and add your URL. You'll receive a signing secret that's used to verify payload authenticity.

Verifying Signatures

Every webhook delivery includes an X-SykikAI-Signature header containing an HMAC-SHA256 hash of the payload body. Always verify this signature before processing the data:

$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $signingSecret);
$headerSig = $_SERVER['HTTP_X_SYKIKAI_SIGNATURE'];

if (!hash_equals($signature, $headerSig)) {
    http_response_code(401);
    exit('Invalid signature');
}

Handling Retries

If your endpoint returns a non-2xx status code or times out (30-second limit), SykikAI will retry the delivery using exponential backoff: after 30 seconds, 2 minutes, and 10 minutes. After 3 failed attempts, the delivery is marked as failed.

If your endpoint fails 10 consecutive deliveries, it will be automatically disabled to prevent resource waste. You can re-enable it from the dashboard after fixing the underlying issue.

Best Practices

• Respond quickly: Return a 200 response immediately, then process the data asynchronously. Long processing times increase the risk of timeouts.
• Handle duplicates: Use the X-SykikAI-Delivery header (a unique UUID per delivery) to detect and ignore duplicate deliveries.
• Log everything: Store raw payloads for debugging. If something goes wrong, having the original data makes troubleshooting much easier.
• Use a queue: Push webhook payloads onto a message queue (Redis, SQS, RabbitMQ) for processing. This decouples receipt from processing and improves reliability.

For complete webhook payload schemas and header documentation, see our API documentation.