Webhooks

Webhooks allow you to receive real-time notifications when events occur, such as when an analysis completes.

Configuration

Webhooks can be configured in two ways:

1. User Interface: Users can manage their webhook settings directly in the dashboard under account settings
2. Admin Setup: Organization administrators can configure webhooks on behalf of users

Contact support@smart11.ai if you need assistance setting up webhooks.

Notification Types

You can enable or disable each notification type independently.

Analysis Done

Sent when an analysis has completed processing.

Event name: analysis_done

{
  "event": "analysis_done",
  "analysis_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "done",
  "completion_rate": 100
}

Field	Type	Description
event	string	Always analysis_done
analysis_id	string	UUID of the completed analysis
status	string	Final status (done or error)
completion_rate	integer	Percentage complete (100 when done)

Analysis Progress

Sent periodically during analysis processing to report progress.

Event name: analysis_completion_rate

{
  "event": "analysis_completion_rate",
  "analysis_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "running",
  "completion_rate": 45
}

Field	Type	Description
event	string	Always analysis_completion_rate
analysis_id	string	UUID of the analysis
status	string	Current status (running, aggregating)
completion_rate	integer	Estimated percentage complete (0-100)

Webhook Delivery

Request Format

Webhooks are delivered as HTTP POST requests to your configured URL:

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: AI-on-the-ball

{
  "event": "analysis_done",
  "analysis_id": "...",
  ...
}

Best Practices

• Respond quickly: Return a 2xx status code within 5 seconds
• Process async: Queue webhook payloads for background processing
• Handle duplicates: Webhooks may be delivered more than once
• Validate events: Verify the analysis_id belongs to your organization

Example Handler

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.json
    event = payload.get('event')

    if event == 'analysis_done':
        analysis_id = payload['analysis_id']
        # Fetch results from API
        print(f"Analysis {analysis_id} completed!")

    elif event == 'analysis_completion_rate':
        progress = payload['completion_rate']
        print(f"Analysis progress: {progress}%")

    return '', 200

// Express.js example
app.post('/webhook', (req, res) => {
  const { event, analysis_id, completion_rate } = req.body;

  if (event === 'analysis_done') {
    console.log(`Analysis ${analysis_id} completed!`);
    // Trigger your post-processing logic
  }

  res.sendStatus(200);
});