Webhooks

Receive real-time event notifications via webhooks.

What are Webhooks?

Webhooks allow neurals to send real-time event notifications to your application. Instead of polling the API to check for updates, webhooks push events to your endpoint as they happen.

This is perfect for building real-time integrations, triggering workflows, and keeping your application in sync with neurals activity.

Supported Events

inbox.organized

Triggered when inbox organization is completed

draft.created

Triggered when a new draft reply is created

meeting.joined

Triggered when a meeting is joined and notes are taken

briefing.sent

Triggered when daily briefing is sent

reminder.sent

Triggered when a reminder is sent

Setting Up Webhooks

1. Configure Webhook URL

Use the API or dashboard to configure your webhook endpoint:

POST /api/webhooks/configure
{
  "url": "https://your-app.com/webhooks/neurals",
  "events": ["inbox.organized", "draft.created"],
  "secret": "your-webhook-secret",  // Optional
  "enabled": true
}

2. Create Webhook Endpoint

Create a POST endpoint in your application to receive webhook events:

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"

@app.route('/webhooks/neurals', methods=['POST'])
def webhook():
    # Verify signature
    signature = request.headers.get('X-Tota-Signature')
    payload = request.get_data()
    
    if signature:
        expected = hmac.new(
            WEBHOOK_SECRET.encode(),
            payload,
            hashlib.sha256
        ).hexdigest()
        
        if not hmac.compare_digest(signature, f"sha256={expected}"):
            return 'Invalid signature', 401
    
    # Process webhook
    data = request.json
    event_type = data['event_type']
    
    if event_type == 'inbox.organized':
        # Handle inbox organized event
        pass
    
    return 'OK', 200

Security & Verification

Signature Verification

If you set a secret, neurals includes an HMAC SHA256 signature in theX-Tota-Signature header. Always verify this signature to ensure requests are from neurals.

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        signature.replace('sha256=', ''),
        expected
    )

Best Practices

• Always verify webhook signatures
• Use HTTPS for webhook endpoints
• Handle duplicate events idempotently
• Return 200 OK quickly and process asynchronously
• Set up monitoring and alerting for webhook failures

Webhook Payload Format

All webhook events follow this format:

{
  "event_type": "inbox.organized",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "total_emails": 42,
    "categorized": {
      "important": 5,
      "meetings": 3,
      "tasks": 8
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "webhook-123"
}

Previous: Python SDK Next: OAuth Setup