How to Use Webhooks

Receive real-time notifications when your predictions complete, instead of polling.

Overview

Webhooks allow Get3W to send an HTTP POST request to your server when a prediction finishes. This is more efficient than polling for long-running tasks like video generation.

Setup

Include a webhook_url in your task submission:

curl -X POST "https://api.get3w.com/api/v3/get3w/flux-dev" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cat in space",
    "webhook_url": "https://your-server.com/webhook"
  }'

Webhook Payload

When the prediction completes (or fails), Get3W sends a POST request to your URL:

{
  "id": "pred_abc123",
  "model": "get3w/flux-dev",
  "status": "completed",
  "outputs": [
    "https://cdn.get3w.com/outputs/image-xxxxx.png"
  ],
  "timings": {
    "inference": 2500
  },
  "created_at": "2024-01-01T12:00:00.000Z",
  "completed_at": "2024-01-01T12:00:03.000Z"
}

Handling Webhooks

Python (Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    data = request.json
    prediction_id = data["id"]
    status = data["status"]

    if status == "completed":
        outputs = data["outputs"]
        # Process your outputs
        print(f"Prediction {prediction_id} completed: {outputs}")
    elif status == "failed":
        error = data.get("error", "Unknown error")
        print(f"Prediction {prediction_id} failed: {error}")

    return "", 200

Node.js (Express)

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
    const { id, status, outputs, error } = req.body;

    if (status === "completed") {
        console.log(`Prediction ${id} completed:`, outputs);
    } else if (status === "failed") {
        console.log(`Prediction ${id} failed:`, error);
    }

    res.sendStatus(200);
});

app.listen(3000);

Requirements

• Your webhook URL must be publicly accessible
• Must accept POST requests with JSON body
• Should return a 2xx status code within 30 seconds
• HTTPS is recommended for security

Retry Policy

If your webhook endpoint returns a non-2xx status code or times out, Get3W will retry the delivery:

Attempt	Delay
1st	Immediate
2nd	10 seconds
3rd	30 seconds
4th	60 seconds

After 4 failed attempts, the webhook delivery is abandoned. You can still retrieve the result via polling.

Verifying Webhooks

To ensure webhook requests are genuinely from Get3W, see Verifying Webhooks.

Next Steps

• Verifying Webhooks — Secure your webhook endpoint
• How to Use Streaming — Real-time progress updates
• How to Get Result — Polling alternative