Webhooks allow you to receive real-time notifications when events occur in Orion, such as when analysis jobs complete. Instead of polling for status updates, configure a webhook endpoint to receive HTTP POST requests with event data.
How Webhooks Work
Create a webhook
Register a webhook URL that will receive notifications.
Associate with events
Link the webhook to specific events or presence names.
Receive notifications
When events occur, Orion sends an HTTP POST request to your webhook URL.
Process the payload
Your server processes the webhook payload and takes appropriate action.
Webhook Configuration
When creating a webhook, you provide:
| Field | Description |
|---|
url | The endpoint URL that will receive webhook notifications |
headers | Optional custom headers to include with webhook requests |
user_id | The user ID associated with this webhook |
presence_name | A name identifying the webhook’s purpose or target |
Endpoints
Example: Setting Up a Webhook
# Create a webhook to receive job completion notifications
curl -X POST '/v1alpha/webhooks/' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://your-server.com/webhooks/orion",
"headers": [
{"name": "X-Webhook-Secret", "value": "your-secret-key"}
],
"user_id": "YOUR_USER_ID",
"presence_name": "job-notifications"
}'
Handling Webhook Payloads
Your webhook endpoint should:
- Respond quickly - Return a 2xx status code within a few seconds
- Verify authenticity - Check custom headers or signatures to verify the request is from Orion
- Process asynchronously - Queue heavy processing for background execution
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/orion', methods=['POST'])
def handle_webhook():
# Verify the request
secret = request.headers.get('X-Webhook-Secret')
if secret != 'your-secret-key':
return jsonify({'error': 'Unauthorized'}), 401
# Process the payload
payload = request.json
# Queue for async processing
process_webhook_async.delay(payload)
# Respond quickly
return jsonify({'status': 'received'}), 200
Make sure your webhook endpoint is publicly accessible and can receive POST
requests from Orion’s servers.
