Webhooks Overview

Webhooks allow you to receive real-time notifications when events occur in Scribe Sight.

How Webhooks Work

1. You register a webhook endpoint URL
2. You select which events to receive
3. When an event occurs, we send an HTTP POST to your endpoint
4. Your server acknowledges receipt with a 2xx response

┌─────────────┐     Event occurs      ┌─────────────┐
│ Scribe Sight │ ─────────────────────▶ │ Your Server │
└─────────────┘    POST /webhook      └─────────────┘
                   with payload

Creating a Webhook

curl -X POST https://scribesight.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/scribesight",
    "events": ["transcription.completed", "content_analysis.completed"]
  }'

Event Payload

All webhook events follow this structure:

{
  "id": "evt_xxxxxxxxxxxx",
  "event": "transcription.completed",
  "api_version": "2026-01-03",
  "created_at": "2026-01-06T15:30:00Z",
  "organization_id": "org_xxxxxxxxxxxx",
  "project_id": "proj_xxxxxxxxxxxx",
  "data": {
    "content_id": "cont_xxxxxxxxxxxx",
    "filename": "sales-call.mp4",
    "duration_seconds": 1847,
    "word_count": 2847
  },
  "links": {
    "api": "https://scribesight.com/api/v1/projects/proj_xxx/content/cont_xxx"
  }
}

Responding to Webhooks

Your endpoint should:

1. Return a 2xx status code within 30 seconds
2. Process the event asynchronously if needed
3. Be idempotent (handle duplicate deliveries)

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/scribesight', methods=['POST'])
def handle_webhook():
    event = request.json
    
    # Queue for async processing
    process_event.delay(event)
    
    # Acknowledge immediately
    return '', 200

Retry Policy

If your endpoint doesn't respond with a 2xx status:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the delivery is marked as exhausted.

Next Steps

• Event Reference — All available events
• Signature Verification — Secure your endpoint
• Best Practices — Production recommendations