WebhookDeliveryFailedError
replicate.errors.WebhookDeliveryFailedError
Stack trace
replicate.errors.WebhookDeliveryFailedError: Webhook delivery failed with status code 500 for URL https://example.com/webhook
at replicate.client._send_webhook (replicate/client.py:123)
at replicate.client._handle_event (replicate/client.py:98)
at replicate.client.poll (replicate/client.py:75) Why it happens
This error happens when the webhook endpoint URL configured in Replicate is unreachable, returns an error status (like 500), or times out. Replicate expects a 2xx HTTP response to confirm successful delivery. Network issues, server errors, or misconfigured endpoints cause this failure.
Detection
Monitor webhook delivery logs in Replicate dashboard or catch WebhookDeliveryFailedError exceptions in your webhook handling code to log failed deliveries and response codes.
Causes & fixes
Webhook endpoint URL is incorrect or unreachable
Verify the webhook URL is correct, publicly accessible, and not blocked by firewalls or IP restrictions.
Webhook endpoint returns HTTP 5xx or 4xx error
Fix server-side errors or authentication issues on the webhook endpoint to ensure it returns HTTP 200 OK on valid requests.
Webhook endpoint times out or is too slow to respond
Optimize webhook handler performance or increase timeout settings to respond promptly within Replicate's webhook timeout window.
Webhook endpoint requires authentication but none is provided
Configure Replicate webhook settings to include necessary authentication headers or tokens, or disable auth if not needed.
Code: broken vs fixed
import os
from replicate import Client
client = Client(api_token=os.environ['REPLICATE_API_TOKEN'])
# This triggers webhook delivery failure if URL is wrong or endpoint errors
client.models.get("some-model").predict(input="test") # webhook fails hereimport os
from replicate import Client
client = Client(api_token=os.environ['REPLICATE_API_TOKEN'])
# Fixed: Ensure webhook URL is correct and endpoint returns 200 OK
client.models.get("some-model").predict(input="test") # webhook succeeds if endpoint fixed
print("Webhook delivery succeeded")Workaround
Catch WebhookDeliveryFailedError exceptions and implement retry logic with exponential backoff or fallback to polling model status instead of relying solely on webhooks.
Prevention
Use reliable, monitored webhook endpoints with health checks and logging. Prefer secure, authenticated URLs and handle retries gracefully to avoid webhook delivery failures.