Webhooks

Receive real-time notifications about events in your Sematryx account via webhooks.

Overview

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

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/aeao",
    "events": ["automation.completed", "automation.failed"],
    "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": "automation.completed",
  "created_at": "2024-01-01T00:00:00Z",
  "data": {
    "automation_id": "auto_1234567890",
    "execution_id": "exec_1234567890",
    "status": "completed",
    "result": {
      "output": "processed_data.csv",
      "records_processed": 1250
    }
  }
}

Payload Structure

  • id: Unique event identifier
  • type: Event type (e.g., "automation.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

automation.completed

Triggered when an automation execution completes successfully

automation.failed

Triggered when an automation execution fails

automation.started

Triggered when an automation execution starts

automation.paused

Triggered when an automation is paused

automation.resumed

Triggered when a paused automation is resumed

optimization.completed

Triggered when an optimization job completes

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