Dashboard Management
Webhooks are managed through the inference.net dashboard:
- Navigate to Webhooks on the sidebar
- Create, test, archive, or restore webhooks through the UI
- Copy your webhook identifier for use in generation requests
Payload Structures
generation.completed
{
"event": "generation.completed",
"timestamp": "ISO 8601 timestamp",
"webhook_id": "webhook identifier",
"generation_id": "generation ID",
"data": {
"state": "Success|Failed",
"stateMessage": "Human readable status",
"request": { /* Original request with metadata */ },
"response": { /* OpenAI format response */ },
"dispatchedAt": "ISO 8601 timestamp",
"finishedAt": "ISO 8601 timestamp"
}
}
slow-group.completed
{
"event": "slow-group.completed",
"timestamp": "ISO 8601 timestamp",
"group_id": "group ID",
"data": {
"group_size": 2,
"status": "completed",
"generations": [
{
"generationId": "generation ID",
"state": "Success|Failed",
"stateMessage": "Human readable status",
"request": { /* Original request */ },
"response": { /* OpenAI format response */ },
"finishedAt": "ISO 8601 timestamp or null"
}
]
}
}
Header | Description | Example |
---|
X-Inference-Event | Event type | generation.completed or slow-group.completed |
X-Inference-Webhook-ID | Webhook identifier | AhALzdz8S |
X-Inference-Generation-ID | Generation ID (if applicable) | XBKcs7F1s2oJ_AHiLMbF4 |
X-Inference-Group-ID | Group ID (for group events) | GRP_XYZ123 |
User-Agent | inference.net webhook agent | Kuzco-Webhook/1.0 |
Content-Type | Always application/json | application/json |
Using Webhooks in Generations
Include the webhook identifier in your generation request metadata:
curl -X POST https://api.inference.net/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/llama-3.1-8b-instruct",
"messages": [{"role": "user", "content": "Hello!"}],
"metadata": {"webhook_id": "YOUR_WEBHOOK_IDENTIFIER"}
}'
Minimal Webhook Handler Examples
Node.js/Express
app.post('/webhook', express.json(), (req, res) => {
res.status(200).json({ received: true });
if (req.body.event === 'generation.completed') {
// Process asynchronously
setImmediate(() => {
console.log('Generation completed:', req.body.generation_id);
// Your processing logic here
});
} else if (req.body.event === 'slow-group.completed') {
// Process group completion asynchronously
setImmediate(() => {
console.log('Group completed:', req.body.group_id);
console.log('Group size:', req.body.data.group_size);
req.body.data.generations.forEach(gen => {
console.log(`Generation ${gen.generationId}: ${gen.state}`);
});
// Your processing logic here
});
}
});
Python/FastAPI
@app.post("/webhook")
async def handle_webhook(payload: dict, background_tasks: BackgroundTasks):
background_tasks.add_task(process_webhook, payload)
return {"received": True}
def process_webhook(payload):
if payload["event"] == "generation.completed":
print(f"Processing generation {payload['generation_id']}")
# Your processing logic here
elif payload["event"] == "slow-group.completed":
print(f"Processing group {payload['group_id']}")
print(f"Group size: {payload['data']['group_size']}")
for gen in payload["data"]["generations"]:
print(f"Generation {gen['generationId']}: {gen['state']}")
# Your processing logic here
func handleWebhook(w http.ResponseWriter, r *http.Request) {
var payload map[string]interface{}
json.NewDecoder(r.Body).Decode(&payload)
// Process asynchronously
go func() {
switch payload["event"] {
case "generation.completed":
// Process single generation
case "slow-group.completed":
data := payload["data"].(map[string]interface{})
fmt.Printf("Group %s completed with %v generations\n",
payload["group_id"], data["group_size"])
// Your processing logic here
}
}()
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
Timing & Limits
Metric | Value | Notes |
---|
Response timeout | 30 seconds | Must respond within this time |
Retry attempts | 3 | With exponential backoff |
Max payload size | 10MB | Typical: 5-50KB |
Delivery time | Under 60 seconds | From completion to webhook |
Response Codes
Code | Meaning | Retry? |
---|
200-299 | Success | No |
400-499 | Client error | No |
500-599 | Server error | Yes |
Timeout | No response in 30s | Yes |
Best Practices Checklist
Common Issues & Solutions
Issue | Solution |
---|
Not receiving webhooks | Check webhook not disabled in dashboard, test connectivity, verify HTTPS URL |
Duplicate webhooks | Implement idempotency, ensure 200 OK response |
Webhooks timing out | Respond immediately, process asynchronously |
Invalid payload | Validate against documented schema |
Test webhook fails | Check endpoint is publicly accessible, returns 200 OK |
Support Resources