Predictions now support webhooks

POST /v1/predictions now accepts a webhook field. Pass a URL and WriftAI will POST to it every time the prediction's status changes. You no longer need to poll to get the result.

Why polling is not always the right answer

Polling works. For short predictions it is completely fine. Check every couple of seconds, exit the loop when status is succeeded, move on.

The problem is variable inference time. A text-to-speech model takes a few seconds for a short phrase and over a minute for a long passage. Poll at a fixed interval and you are either making unnecessary requests on fast runs or adding latency on slow ones. For anything running as part of a pipeline, that latency compounds across every step.

How to use it

Pass a webhook object when creating a prediction:

1curl https://api.wrift.ai/v1/predictions \
2  -H "Authorization: Bearer $WRIFTAI_ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "owner/model-name",
6    "input": { "prompt": "your prompt here" },
7    "webhook": {
8      "url": "https://your-server.com/webhooks/wriftai"
9    }
10  }'

What you receive

Each event is a POST with the full prediction object as the body:

1{
2  "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
3  "status": "succeeded",
4  "model": {
5    "owner": "owner",
6    "name": "model-name"
7  },
8  "input": {
9    "prompt": "your prompt here"
10  },
11  "output": "The model response text.",
12  ...
13}

For failed predictions, output is null and error is set.

Handling events

Since your handler receives events for every status change, including pending and started, return 2xx for all of them. Only act on the statuses your application cares about.

Never do slow work inside the handler itself. Downloading a file, writing to a database, calling another service: all of that should go in a background task. Return a response immediately, then do the work.

Events can also be delivered more than once. Make your handler idempotent: processing the same event twice should produce the same result as processing it once.

Chaining predictions

If your application feeds the output of one prediction into the next, webhooks remove the polling layer between steps. When a succeeded event arrives, the output is already in the payload. Create the next prediction immediately from inside your handler.

One thing to be aware of: delivery order is not guaranteed. A succeeded event can arrive before an earlier started event in rare cases. Write your handler to check the status in the payload rather than assuming events arrive in sequence.

When delivery fails

WriftAI retries if your endpoint returns a 429 or 5xx response. If retries are exhausted, you will need to recover manually. Use GET /v1/predictions/{id} to check the current state of any prediction you created. Do not rely solely on webhooks for critical work without a recovery path.

Signature verification

Webhook secrets for signing requests are not yet supported. For now, verify incoming requests by checking the prediction ID in the payload against your own records. Confirm it is a prediction you actually created before acting on the event.

Secrets are on the roadmap.