Webhooks

Overview

Webhooks allow you to receive push notifications instead of polling the API. When an event occurs, Decisio sends an HTTP POST request to your configured URL.

Available Events

Setting Up Webhooks

Via Dashboard

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select events to subscribe to
5. Optionally add a description
6. Click Create

Via API

POST /v1/webhooks
Content-Type: application/json
Authorization: Bearer <token>

{
  "url": "https://yourserver.com/webhooks/decisio",
  "events": ["decision.created", "alert.created"],
  "description": "Production webhook"
}

Webhook Payload

Each webhook delivery includes a JSON payload with the event details:

{
  "id": "evt_abc123",
  "type": "decision.created",
  "created_at": "2025-01-15T10:30:00Z",
  "tenant_id": "tenant_xyz",
  "data": {
    "id": "dec_456",
    "agent": "astra",
    "type": "price_increase",
    "sku": "ELEC-HDMI-001",
    "recommendation": {
      "current_price": 599,
      "new_price": 649,
      "expected_impact": "+4500"
    },
    "confidence": 0.94,
    "status": "pending"
  }
}

Webhook Headers

Each request includes these headers:

Verifying Signatures

Always verify webhook signatures to ensure requests are from Decisio:

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

The signing secret is shown when you create the webhook. Store it securely.

Responding to Webhooks

Your endpoint must:

• Return 2xx status code to acknowledge receipt
• Respond within 30 seconds
• Handle duplicate deliveries (use delivery ID for deduplication)

Retry Policy

If your endpoint fails (non-2xx or timeout), Decisio retries with exponential backoff:

After 5 failed attempts, the delivery is marked as failed. You can manually retry failed deliveries from the webhook logs.

Testing Webhooks

Use the dashboard to test your endpoint:

1. Go to Settings → Webhooks
2. Click on your webhook
3. Click Send Test Event
4. Select an event type
5. View the request and response

For local development, use a tunnel service like ngrok:

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/decisio

Webhook Logs

View delivery history and debug issues:

• Last 7 days of deliveries retained
• See request payload and response
• Filter by event type or status
• Manually retry failed deliveries

Best Practices

• Always verify signatures before processing
• Use idempotency keys to handle duplicates
• Acknowledge quickly, process asynchronously
• Set up monitoring for failed deliveries
• Use separate endpoints for different event types if needed