Webhook Integration

Introduction

Webhooks allow you to receive real-time event notifications from the I Hate PPT system, enabling automatic integration and responses between systems.

How It Works

Configure Webhook - Configure the URL to receive events in the console
Event Trigger - When specific events occur, the system sends HTTP POST requests
Handle Events - Your server receives and processes event data
Response Confirmation - Return HTTP 200 status code to confirm receipt

Supported Events

PPT Generation Events

ppt.generation.started - PPT generation started
ppt.generation.completed - PPT generation completed
ppt.generation.failed - PPT generation failed
ppt.generation.cancelled - PPT generation cancelled

Edit Events

ppt.edit.started - PPT editing started
ppt.edit.completed - PPT editing completed
ppt.edit.failed - PPT editing failed

File Events

file.uploaded - File upload completed
file.processed - File processing completed
file.deleted - File deleted

User Events

user.registered - User registration
user.subscribed - User subscription
user.unsubscribed - User unsubscribed

Configure Webhook

1. Create Webhook

curl -X POST https://api.ihateppt.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "events": ["ppt.generation.completed", "ppt.generation.failed"],
    "secret": "your_webhook_secret"
  }'

2. Verify Webhook

The system will send a verification request to your URL:

POST https://your-domain.com/webhook
Content-Type: application/json

{
  "type": "webhook.verification",
  "data": {
    "challenge": "verification_challenge_string"
  }
}

Your server needs to return the challenge value:

{
  "challenge": "verification_challenge_string"
}

Event Format

Request Headers

POST https://your-domain.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=signature
X-Webhook-Timestamp: 1640995200
X-Webhook-Event: ppt.generation.completed

Event Data

{
  "id": "evt_123456789",
  "type": "ppt.generation.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "ppt_id": "ppt_123456",
    "user_id": "user_789",
    "title": "AI Development Trends",
    "pages": 8,
    "download_url": "https://api.ihateppt.com/v1/ppt/ppt_123456/download",
    "generation_time": 25.5,
    "cost": 30
  }
}

Signature Verification

Calculate Signature

import hmac
import hashlib
import time

def verify_webhook_signature(payload, signature, secret, timestamp):
    # Build signature string
    message = f"{timestamp}.{payload}"
    
    # Calculate HMAC-SHA256 signature
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Verify signature
    return hmac.compare_digest(f"sha256={expected_signature}", signature)

Verification Example

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # Get request headers
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    event_type = request.headers.get('X-Webhook-Event')
    
    # Get request body
    payload = request.get_data(as_text=True)
    
    # Verify signature
    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET, timestamp):
        return jsonify({'error': 'Invalid signature'}), 400
    
    # Handle event
    event_data = request.get_json()
    handle_webhook_event(event_type, event_data)
    
    return jsonify({'status': 'success'}), 200

def handle_webhook_event(event_type, event_data):
    if event_type == 'ppt.generation.completed':
        # Handle PPT generation completed event
        ppt_id = event_data['data']['ppt_id']
        download_url = event_data['data']['download_url']
        # Execute follow-up operations...
        
    elif event_type == 'ppt.generation.failed':
        # Handle PPT generation failed event
        error_message = event_data['data']['error']
        # Log error...

Retry Mechanism

Retry Strategy

Retry Count: Maximum 3 times
Retry Intervals: 1 second, 5 seconds, 30 seconds
Timeout: 30 seconds
Retry Conditions: Non-200 HTTP status codes

Retry Event

{
  "id": "evt_123456789",
  "type": "webhook.retry",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "original_event_id": "evt_123456788",
    "retry_count": 2,
    "next_retry_at": "2024-01-15T10:30:30Z"
  }
}

Best Practices

Security

Verify Signatures - Always verify webhook signatures
Use HTTPS - Ensure webhook URLs use HTTPS
Limit Access - Restrict access to webhook endpoints
Log Events - Log all webhook events

Reliability

Idempotency - Ensure processing logic is idempotent
Fast Response - Return response within 5 seconds
Error Handling - Properly handle various error scenarios
Monitoring Alerts - Monitor webhook processing status

Performance

Async Processing - Use queues for asynchronous event processing
Batch Processing - Batch process similar events
Cache Data - Cache frequently accessed data
Optimize Database - Optimize database queries and updates

Testing Webhooks

Using ngrok for Testing

# Install ngrok
npm install -g ngrok

# Start local server
python app.py

# Start ngrok in another terminal
ngrok http 3000

# Configure webhook with ngrok URL
curl -X POST https://api.ihateppt.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhook",
    "events": ["ppt.generation.completed"]
  }'

Using Test Tools

# Send test event
curl -X POST https://api.ihateppt.com/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "wh_123456",
    "event_type": "ppt.generation.completed"
  }'

Frequently Asked Questions

Q: What to do if webhook doesn't receive events?

Check if webhook URL is accessible
Verify signature verification logic is correct
Check if webhook configuration is correct
Check server logs for errors

Q: How to handle duplicate events?

Use event ID for deduplication
Implement idempotent processing logic
Record processed event IDs

Q: What to do if webhook response times out?

Optimize processing logic to reduce response time
Use asynchronous processing mechanisms
Increase server resources

Q: How to monitor webhook status?

View webhook event logs
Set up monitoring alerts
Regularly check webhook configuration

Get Started with Webhooks - Check out API Reference for detailed API interface documentation.