Replicate logo
Home / Topics / Webhooks

Set up webhooks

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 JavaScript 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 start
  • output: each time a prediction generates an output (note that predictions can generate multiple outputs)
  • logs: each time log output is generated by a prediction
  • completed: 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",
});
Tip

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