Webhooks API

Use webhooks when your systems need to react to PolyAI events in real time–for example, triggering incident response when an alert fires or updating a dashboard. Webhooks include HMAC-SHA256 signatures and automatic retries, with support for secret rotation.

The Webhooks API lets you register HTTP endpoints that receive real-time notifications when events occur in your PolyAI account. Webhooks are currently used by the Alerts API and will expand to other services in the future.

Key features

• Signed delivery - Every webhook includes an HMAC-SHA256 signature you can verify
• Automatic retries - Failed deliveries retry with exponential backoff
• Secret rotation - Rotate signing secrets without recreating the endpoint

Limits

Requests to create a webhook endpoint beyond the limit return a 409 Conflict error.

Event types

Webhook headers

Each webhook request includes these headers:

Retry policy

Failed webhook deliveries are retried with exponential backoff:

Retried failures:

• Timeout
• Network error
• HTTP 408, 429, 5xx

Not retried:

• Other 4xx errors

Signature verification

Verify webhook signatures to ensure requests are from PolyAI.

Algorithm: HMAC-SHA256

Signed message format: {timestamp}.{raw_request_body}

import hmac
import hashlib
import time
def verify_webhook(payload: bytes, timestamp: str, signature: str, secret: str) -> bool:
    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False
    
    # Compute expected signature
    message = f"{timestamp}.{payload.decode('utf-8')}"
    expected = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Constant-time comparison
    return hmac.compare_digest(expected, signature)

Authentication

All Webhooks API endpoints use API key authentication with the x-api-key header. Resources are automatically scoped to your account.