Fire-and-Forget AI Jobs with Webhook Callbacks

Modern applications increasingly need to offload expensive AI operations without blocking user requests. Whether you're processing documents, generating images, or analyzing data, waiting for Claude to finish can create poor user experiences and waste server resources.

AiPayGent's async endpoints solve this problem elegantly: send your AI job once, get a callback when it's done. No polling. No timeouts. Just clean, event-driven architecture.

The Problem: Synchronous AI Bottlenecks

Traditional API calls are synchronous. You send a request, wait for the response, then continue. This works fine for quick operations, but AI tasks can take 10+ seconds:

• Your HTTP request times out after 30 seconds
• Users see spinners while waiting for Claude to think
• Server resources stay tied up during processing
• You need complex retry logic and state management

Webhooks eliminate these pain points. Fire your job, immediately return a response to your user, and process the result when Claude finishes.

How AiPayGent Async Works

The async endpoints accept your prompt, store it, process it asynchronously, and POST the result to your webhook URL when complete. You get:

• Instant response with a job_id
• No waiting—your API returns immediately
• Automatic callback to your webhook with full results
• Built-in retries if your webhook is temporarily down

Example: Async Text Generation

Let's build a real example. Say you're a SaaS platform that generates marketing copy. Users shouldn't wait 15 seconds for Claude's response—instead, you'll queue the job and notify them via email when it's ready.

Step 1: Create Your Webhook Endpoint

First, set up a simple endpoint that receives the result. Here's a Python example using Flask:

from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhooks/aipaygent', methods=['POST'])
def handle_aipaygent_webhook():
    data = request.json
    job_id = data.get('job_id')
    status = data.get('status')
    result = data.get('result')
    
    if status == 'completed':
        print(f"Job {job_id} completed!")
        print(f"Result: {result}")
        # Save to database, send email, update UI, etc.
    elif status == 'failed':
        print(f"Job {job_id} failed: {data.get('error')}")
    
    return {'received': True}, 200

if __name__ == '__main__':
    app.run(port=5000)

Step 2: Submit an Async Job

Now submit a job to AiPayGent. Here's the cURL command:

curl -X POST https://api.aipaygent.xyz/async/text-generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a compelling product description for premium coffee beans",
    "webhook_url": "https://yourapp.com/webhooks/aipaygent",
    "model": "claude-opus",
    "max_tokens": 500
  }'

And here's the Python equivalent:

import requests
import json

api_key = "YOUR_API_KEY"
webhook_url = "https://yourapp.com/webhooks/aipaygent"

payload = {
    "prompt": "Write a compelling product description for premium coffee beans",
    "webhook_url": webhook_url,
    "model": "claude-opus",
    "max_tokens": 500
}

response = requests.post(
    "https://api.aipaygent.xyz/async/text-generate",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json=payload
)

data = response.json()
print(f"Job ID: {data['job_id']}")
print(f"Status: {data['status']}")

Example Response

{
  "job_id": "job_abc123xyz789",
  "status": "queued",
  "created_at": "2024-01-15T10:30:45Z",
  "webhook_url": "https://yourapp.com/webhooks/aipaygent"
}

Your endpoint returns immediately. Seconds later, AiPayGent POSTs the result to your webhook:

{
  "job_id": "job_abc123xyz789",
  "status": "completed",
  "created_at": "2024-01-15T10:30:45Z",
  "completed_at": "2024-01-15T10:32:12Z",
  "result": {
    "text": "Discover the extraordinary essence of our premium coffee beans...",
    "tokens_used": 187,
    "model": "claude-opus"
  }
}

Pricing & Free Tier

Good news: Your first 10 API calls per day are completely free. After that, you can either:

• Use a prepaid API key (pay as you go)
• Pay with USDC on Base blockchain for maximum flexibility

To add credits, visit the /buy-credits endpoint or your dashboard.

Best Practices

• Idempotency: Store the job_id in your database immediately after submitting. If you receive duplicate webhooks, your system won't double-process.
• Timeout Handling: Set a reasonable timeout (e.g., 5 minutes). If no webhook arrives, query the job status directly.
• Retry Logic: AiPayGent will retry failed webhooks, but implement your own for critical operations.
• Security: Validate webhook signatures if you implement them (check AiPayGent docs for HMAC details).

Explore More

AiPayGent offers 140+ endpoints across text generation, image analysis, embeddings, and more. All support async workflows with webhooks.

Discover all available endpoints: https://api.aipaygent.xyz/discover

Check the complete API specification: https://api.aipaygent.xyz/openapi.json