Skip to main content
skill CX Codex

replicate-webhooks — Claude Code skill: what it does, how to install

Receive and verify Replicate webhooks across Express or FastAPI. Handles model prediction lifecycle events and HMAC signature verification.

MIT 198 installs ★ 103 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill replicate-webhooks -a claude-code
Open on GitHub

What replicate-webhooks does

This skill supplies implementation patterns and verification rules for incoming Replicate webhook requests. It guides the agent through parsing webhook-id, webhook-timestamp, and webhook-signature headers using HMAC SHA-256. Webhook routes must consume raw request bodies via express.raw(), or signature validation will fail immediately.

The logic handles space-separated signatures sent by Replicate, applies a 300-second freshness window to block replay attempts, and organizes handlers for prediction statuses: starting, processing, succeeded, failed, and canceled. Running it requires setting REPLICATE_WEBHOOK_SECRET with the whsec_ prefix, while local debugging runs via hookdeck-cli.

What it helps with

  • set up an Express or FastAPI endpoint for Replicate webhooks
  • verify incoming payloads against webhook-signature using HMAC SHA-256
  • handle prediction lifecycle transitions from starting to succeeded
  • prevent replay attacks using the 300-second timestamp window

Example prompts for the agent

  • Create an Express endpoint to verify Replicate webhooks with raw body parsing
  • Handle Replicate prediction events and extract output on succeeded status
  • How do I verify the webhook-signature header from Replicate in FastAPI?

How to install replicate-webhooks

1Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill replicate-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/replicate-webhooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/replicate-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about replicate-webhooks

How do I install replicate-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill replicate-webhooks -a claude-code.

What does replicate-webhooks do?

It provides ready-to-use patterns for validating Replicate HMAC SHA-256 signatures and routing prediction events like starting, processing, and succeeded.

What secret format does Replicate signature verification expect?

It requires the REPLICATE_WEBHOOK_SECRET environment variable starting with whsec_. The verification logic strips this prefix and decodes the base64 secret.

Source text

SKILL.md · MIT
---
name: replicate-webhooks
description: >
  Receive and verify Replicate webhooks. Use when setting up Replicate webhook
  handlers, debugging signature verification, or handling prediction events
  like start, output, logs, or completed.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Replicate Webhooks

## When to Use This Skill

- Setting up Replicate webhook handlers
- Debugging signature verification failures
- Understanding Replicate event types and payloads
- Handling prediction lifecycle events (start, output, logs, completed)

## Essential Code (USE THIS)

### Express Webhook Handler

```javascript
const express = require('express');
const crypto = require('crypto');

const app = express();

// CRITICAL: Use express.raw() for webhook endpoint - Replicate needs raw body
app.post('/webhooks/replicate',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // Get webhook headers
    const webhookId = req.headers['webhook-id'];
    const webhookTimestamp = req.headers['webhook-timestamp'];
    const webhookSignature = req.headers['webhook-signature'];

    // Verify we have required headers
    if (!webhookId || !webhookTimestamp || !webhookSignature) {
      return res.status(400).json({ error: 'Missing required webhook headers' });
    }

    // Manual signature verification (recommended approach)
    const secret = process.env.REPLICATE_WEBHOOK_SECRET; // whsec_xxxxx from Replicate
    const signedContent = `${webhookId}.${webhookTimestamp}.${req.body}`;

    try {
      // Extract base64 secret after 'whsec_' prefix
      const secretBytes = Buffer.from(secret.split('_')[1], 'base64');
      const expectedSignature = crypto
        .createHmac('sha256', secretBytes)
        .update(signedContent)
        .digest('base64');

      // Replicate can send multiple signatures, check each one
      const signatures = webhookSignature.split(' ').map(sig => {
        const parts = sig.split(',');
        return parts.length > 1 ? parts[1] : sig;
      });

      const isValid = signatures.some(sig => {
        try {
          return crypto.timingSafeEqual(
            Buffer.from(sig),
            Buffer.from(expectedSignature)
          );
        } catch {
          return false; // Different lengths = invalid
        }
      });

      if (!isValid) {
        return res.status(400).json({ error: 'Invalid signature' });
      }

      // Check timestamp to prevent replay attacks (5-minute window)
      const timestamp = parseInt(webhookTimestamp, 10);
      const currentTime = Math.floor(Date.now() / 1000);
      if (currentTime - timestamp > 300) {
        return res.status(400).json({ error: 'Timestamp too old' });
      }
    } catch (err) {
      console.error('Signature verification error:', err);
      return res.status(400).json({ error: 'Invalid signature' });
    }

    // Parse the verified webhook body
    const prediction = JSON.parse(req.body.toString());

    // Handle the prediction based on its status
    console.log('Prediction webhook received:', {
      id: prediction.id,
      status: prediction.status,
      version: prediction.version
    });

    switch (prediction.status) {
      case 'starting':
        console.log('Prediction starting:', prediction.id);
        break;
      case 'processing':
        console.log('Prediction processing:', prediction.id);
        if (prediction.logs) {
          console.log('Logs:', prediction.logs);
        }
        break;
      case 'succeeded':
        console.log('Prediction completed successfully:', prediction.id);
        console.log('Output:', prediction.output);
        break;
      case 'failed':
        console.log('Prediction failed:', prediction.id);
        console.log('Error:', prediction.error);
        break;
      case 'canceled':
        console.log('Prediction canceled:', prediction.id);
        break;
      default:
        console.log('Unknown status:', prediction.status);
    }

    res.status(200).json({ received: true });
  }
);
```

## Common Prediction Statuses

| Status | Description | Common Use Cases |
|--------|-------------|------------------|
| `starting` | Prediction is initializing | Show loading state in UI |
| `processing` | Model is running | Display progress, show logs if available |
| `succeeded` | Prediction completed successfully | Process final output, update UI |
| `failed` | Prediction encountered an error | Show error message to user |
| `canceled` | Prediction was canceled | Clean up resources, notify user |

## Environment Variables

```bash
# Your webhook signing secret from Replicate
REPLICATE_WEBHOOK_SECRET=whsec_your_secret_here
```

## Local Development

For local webhook testing, install the Hookdeck CLI:

```bash
```

Then start the tunnel:

```bash
npx hookdeck-cli listen 3000 replicate --path /webhooks/replicate
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Reference Materials

- [What are Replicate webhooks](references/overview.md) — Event types and payload structure
- [Setting up webhooks](references/setup.md) — Dashboard configuration and signing secret
- [Signature verification](references/verification.md) — Verification algorithm and common issues

## Resources for Implementation

### Framework Examples
- [Express implementation](examples/express/) — Node.js with Express
- [Next.js implementation](examples/nextjs/) — React framework with API routes
- [FastAPI implementation](examples/fastapi/) — Python async framework

### Documentation
- [Official Replicate webhook docs](https://replicate.com/docs/topics/webhooks)
- [Webhook setup guide](https://replicate.com/docs/topics/webhooks/setup-webhook)
- [Webhook verification guide](https://replicate.com/docs/topics/webhooks/verify-webhook)

## Recommended: webhook-handler-patterns

Enhance your webhook implementation with these patterns:

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md)
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhooks
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository events
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify store events
- [clerk-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/clerk-webhooks) - Clerk authentication events
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

© hookdeck · MIT · hookdeck/webhook-skills

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
cursor-webhooks Set up a handler for Cursor Cloud Agent webhooks, verify request signatures, and respond to agent status changes. Useful when wiring webhook events into an app. CX Codex +1 200installs deepgram-webhooks A skill for receiving and verifying Deepgram webhooks. Use when you need to handle asynchronous transcription results or build a callback handler for completed transcription requests. CX Codex +1 200installs gitlab-webhooks Skill for handling GitLab webhooks with signature and token verification. Use it to set up webhook handlers for push, merge request, and pipeline events, or debug authentication failures. CX Codex +1 199installs hookdeck-event-gateway-webhooks Verifies webhook signatures from Hookdeck Event Gateway. Webhooks arrive with an x-hookdeck-signature header — the skill provides ready-to-use functions for HMAC SHA-256 validation. CX Codex +1 198installs outpost The outpost skill helps plan event delivery from a SaaS or API platform to HTTP endpoints, queues, and cloud event buses. CX Codex +1 196installs fusionauth-webhooks Teach your coding assistant to receive FusionAuth webhooks and verify JWT signatures. Useful when wiring auth events into Express or FastAPI. CX Codex +1 196installs chargebee-webhooks Sets up and verifies Chargebee webhooks using Basic Auth. Guides subscription and payment event handling across Express, Next.js, and FastAPI. CX Codex +1 195installs webflow-webhooks webflow-webhooks shows how to receive Webflow events, validate request signatures, and debug handlers. Useful for forms, ecommerce orders, and CMS webhooks. CX Codex +1 190installs

Project sponsors

Companies that keep this analytics open