Webhooks

Receive real-time notifications about optimization events in your Sematryx account via webhooks. Get notified when optimizations start, complete, fail, or when important status changes occur.

Overview

Webhooks allow you to receive real-time notifications when optimization events occur in your Sematryx account. Instead of polling the API, Sematryx will send HTTP POST requests to your specified URL when events happen.

What events are available? Webhooks notify you about optimization lifecycle events: when optimizations start, complete successfully, fail, get cancelled, stagnate (no improvement), timeout, when the strategy changes during execution, or when context/metadata is updated. This enables you to build reactive systems that respond immediately to optimization status changes without constant polling.

Benefits

  • • Real-time event notifications
  • • Reduced API polling overhead
  • • More efficient resource usage
  • • Better integration with your systems

Creating a Webhook

Create a webhook endpoint to receive notifications:

POST /v1/webhooks
curl -X POST https://api.sematryx.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/sematryx",
    "events": ["optimization.completed", "optimization.failed", "optimization.started"],
    "secret": "your-webhook-secret"
  }'

Request Body

  • url (required): HTTPS URL to receive webhook events
  • events (required): Array of event types to subscribe to
  • secret (optional): Secret for verifying webhook signatures
  • active (optional): Whether the webhook is active (default: true)

Webhook Payload

All webhook requests are sent as HTTP POST requests with JSON payloads:

Example webhook payload
{
  "id": "evt_1234567890",
  "type": "optimization.completed",
  "created_at": "2024-01-01T00:00:00Z",
  "data": {
    "optimization_id": "opt_1234567890",
    "status": "completed",
    "result": {
      "best_solution": [0.001, -0.002, 0.003],
      "best_fitness": 0.000014,
      "evaluations": 847,
      "duration_seconds": 2.34
    }
  }
}

Payload Structure

  • id: Unique event identifier
  • type: Event type (e.g., "optimization.completed")
  • created_at: ISO 8601 timestamp of when the event occurred
  • data: Event-specific data object

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are from Sematryx. The signature is sent in the X-Sematryx-Signature header.

Node.js Example

Verify webhook signature in Node.js
import crypto from 'crypto'

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(JSON.stringify(payload))
  const expectedSignature = hmac.digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

Python Example

Verify webhook signature in Python
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

Available Events

optimization.started

Triggered when an optimization job starts

optimization.completed

Triggered when an optimization job completes successfully

optimization.failed

Triggered when an optimization job fails

optimization.cancelled

Triggered when an optimization job is cancelled

optimization.stagnated

Triggered when an optimization has stagnated (no improvement for extended period)

optimization.timeout

Triggered when an optimization exceeds its time limit

strategy.changed

Triggered when the optimization strategy changes during execution

context.updated

Triggered when optimization context or metadata is updated

Webhook Retries

If your webhook endpoint returns a non-2xx status code, Sematryx will retry the delivery:

  • Immediate: First retry after 1 second
  • 1 minute: Second retry after 1 minute
  • 5 minutes: Third retry after 5 minutes
  • 1 hour: Fourth retry after 1 hour
  • 24 hours: Final retry after 24 hours

After all retries are exhausted, the webhook will be marked as failed. You can view failed webhook deliveries in the dashboard.

Best Practices

✅ Do

  • Always verify webhook signatures
  • Use HTTPS endpoints only
  • Respond quickly (within 5 seconds)
  • Return 2xx status codes for successful processing
  • Implement idempotency for duplicate events
  • Log all webhook events for debugging

❌ Don't

  • Perform long-running operations in webhook handlers
  • Ignore signature verification
  • Use HTTP (non-secure) endpoints
  • Return errors for expected events
  • Block on external API calls