Set up webhooks
Table of contents
To receive webhook events, specify a webhook
URL in the request body when creating a prediction or a training.
Here’s an example using the Replicate client to create a prediction and request a webhook event when the prediction is completed:
await replicate.predictions.create({
version: "d55b9f2d...",
input: { prompt: "call me later maybe" },
webhook: "https://example.com/replicate-webhook",
webhook_events_filter: ["completed"], // optional
});
Webhook events filter
By default, we will send requests to your webhook URL whenever there are new outputs or the prediction has finished. You can change which events trigger webhook requests by specifying webhook_events_filter
in the prediction request:
start
: immediately on prediction startoutput
: each time a prediction generates an output (note that predictions can generate multiple outputs)logs
: each time log output is generated by a predictioncompleted
: when the prediction reaches a terminal state (succeeded/canceled/failed)
For example, if you only wanted requests to be sent at the start and end of the prediction, you would provide:
{
"input": {
"text": "Alice"
},
"webhook": "https://example.com/my-webhook",
"webhook_events_filter": ["start", "completed"]
}
Requests for event types output
and logs
will be sent at most once every 500ms.
If you request start
and completed
webhooks, then they’ll always be sent regardless of throttling.
Webhooks for trainings
In addition to predictions, you can also receive webhooks when fine-tuning models with the training API:
await replicate.trainings.create({
version: "d55b9f2d...",
destination: "my-username/my-model",
input: { training_data: "..." },
webhook: "https://example.com/replicate-webhook",
});
Add query params to your webhook URL to pass along extra metadata, like an internal ID you’re using for a prediction. For example: https://example.com/replicate-webhook?customId=123
Example resources
- See the Node.js client webhook docs.
- See the Python client webhook docs.
- See predictions.create and trainings.create API docs.
- See Scribble Diffusion’s codebase for a reference implementation in JavaScript.
- Read our streaming guide to learn how to consume server-sent events (SSEs) from language models.