Replicate webhooks provide real-time updates about your AI model predictions, eliminating the need for constant polling. This guide will walk you through setting up, receiving, and verifying Replicate webhooks to build robust AI-powered applications.

What are Replicate Webhooks?

A Replicate webhook is an HTTP POST request sent to your specified endpoint during a prediction's lifecycle. Instead of repeatedly polling the API to check if your prediction is complete, Replicate automatically notifies you about status changes.

Webhooks are essential for capturing prediction metadata and output files before they're automatically deleted (files are removed after 1 hour), enabling real-time notifications for long-running predictions, and building automated model processing pipelines.

Setting Up Replicate Webhooks

Specify a Webhook URL

When creating a prediction, include a webhook parameter with your target URL:

prediction.json

{
  "input": {
    "prompt": "A beautiful sunset over mountains"
  },
  "webhook": "https://your-app.com/api/replicate-webhook"
}

Configure Webhook Event Filters

Use webhook_events_filter to control when webhooks are sent. Available event types:

start - Triggers when prediction starts
output - Triggers when prediction generates output
logs - Triggers on log generation
completed - Triggers when prediction reaches final state

prediction-with-filters.json

{
  "input": {
    "prompt": "A beautiful sunset over mountains"
  },
  "webhook": "https://your-app.com/api/replicate-webhook",
  "webhook_events_filter": ["start", "completed"]
}

Note: Webhook requests for output and logs are throttled to at most once every 500ms.

Receiving Webhook Payloads

Webhook Payload Structure

Replicate sends a JSON prediction object containing details like status, input, output, and logs:

webhook-payload.json

{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "input": {
    "prompt": "A beautiful sunset over mountains"
  },
  "output": [
    "https://replicate.delivery/pbxt/abc123/output.png"
  ],
  "logs": "Processing complete",
  "metrics": {
    "predict_time": 2.5
  }
}

Handling Best Practices

When receiving webhooks, follow these critical guidelines:

•Respond quickly - Return a 2xx status code within seconds
•Implement idempotency - Handle potential duplicate webhooks by checking the prediction ID
•Expect out-of-order delivery - Webhooks may arrive in unexpected sequences
•Ignore post-terminal webhooks - Disregard webhooks after receiving a terminal state (succeeded, failed, canceled)

Retry Mechanism

If webhook delivery fails, Replicate retries using exponential backoff. The final retry is sent approximately 1 minute after prediction completion. Ensure your endpoint is resilient and can handle retries gracefully.

Verifying Webhook Signatures

Why Signature Verification is Critical

Verifying webhook signatures ensures requests genuinely originate from Replicate, preventing unauthorized requests and potential replay attacks. Never skip verification in production environments.

Verification Process

Replicate includes three critical headers in webhook requests:

webhook-id - Unique webhook identifier
webhook-timestamp - Unix timestamp of the request
webhook-signature - HMAC-SHA256 signature

Follow these steps to verify authenticity:

Retrieve your webhook signing key from the Replicate API (cache it locally for performance)
Construct signed content: ${webhook_id}.${webhook_timestamp}.${body}
Compute HMAC-SHA256 signature using your signing key
Compare computed signature with the webhook-signature header using constant-time comparison
Validate the timestamp is within acceptable tolerance to prevent replay attacks

Node.js Example

verify-webhook.js

const crypto = require('crypto');

async function verifyReplicateWebhook(req, signingKey) {
  const webhookId = req.headers['webhook-id'];
  const webhookTimestamp = req.headers['webhook-timestamp'];
  const webhookSignature = req.headers['webhook-signature'];

  // Validate timestamp (prevent replay attacks)
  const currentTime = Math.floor(Date.now() / 1000);
  const timestamp = parseInt(webhookTimestamp, 10);
  if (Math.abs(currentTime - timestamp) > 300) {
    throw new Error('Webhook timestamp too old');
  }

  // Construct signed content
  const signedContent = `${webhookId}.${webhookTimestamp}.${req.body}`;

  // Compute HMAC-SHA256 signature
  const expectedSignature = crypto
    .createHmac('sha256', signingKey)
    .update(signedContent)
    .digest('hex');

  // Use constant-time comparison
  if (!crypto.timingSafeEqual(
    Buffer.from(webhookSignature),
    Buffer.from(expectedSignature)
  )) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

Testing Webhooks Locally

Using ngrok for Local Development

During development, your local server isn't publicly accessible. Use ngrok to create a secure tunnel and receive real webhooks:

terminal

# Install and run ngrok to expose your local server
npx ngrok http 3000

Ngrok generates a temporary public HTTPS URL (e.g., https://abc123.ngrok.io) that you can use as your webhook endpoint:

create-prediction.js

await replicate.predictions.create({
  version: "d55b9f2d...",
  input: { prompt: "mountain sunset" },
  webhook: "https://abc123.ngrok.io/replicate-webhook"
});

Note: Ngrok URLs expire after ~2 hours. Replace with your production endpoint when deploying.

Never Miss a Replicate Webhook Event

Hooklistener provides instant webhook URLs to receive Replicate events reliably. Capture, inspect, and debug webhooks with signature verification, request replay, and real-time monitoring. Perfect for development and production environments.

Start Receiving Webhooks Free →

Common Use Cases

Persist Prediction Data

Save prediction outputs and metadata before automatic deletion. Files are removed after 1 hour, making webhooks essential for long-term storage.

Build Processing Pipelines

Chain multiple models together by triggering new predictions when previous ones complete, creating sophisticated AI workflows.

Send Real-Time Notifications

Notify users immediately when their long-running predictions complete, improving user experience for time-intensive AI tasks.

Replicate Webhooks: A Complete Guide