replit-webhooks-events
Implement Replit webhook signature validation and event handling.Use when setting up webhook endpoints, implementing signature verification,or handling Replit event notifications securely.Trigger with phrases like "replit webhook", "replit events","replit webhook signature", "handle replit events", "replit notifications".
When & Why to Use This Skill
This Claude skill streamlines the implementation of secure Replit webhook systems by providing robust signature validation and structured event handling patterns. It automates the creation of secure endpoints with built-in HMAC-SHA256 verification and replay attack protection, ensuring reliable communication between Replit and external services. Ideal for developers building event-driven architectures, it covers everything from initial setup to advanced idempotency handling.
Use Cases
- Securely validating incoming Replit webhook signatures using timing-safe HMAC-SHA256 comparisons to prevent unauthorized access.
- Implementing replay attack protection by verifying webhook timestamps to ensure requests are processed within a valid time window.
- Architecting scalable event-driven systems by routing Replit resource events (created, updated, deleted) to dedicated logic handlers.
- Ensuring data integrity and preventing duplicate processing through Redis-based idempotency checks for high-reliability integrations.
- Streamlining the development workflow by setting up local testing environments with ngrok and Replit CLI for webhook debugging.
| name | replit-webhooks-events |
|---|---|
| description | | |
| allowed-tools | Read, Write, Edit, Bash(curl:*) |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
Replit Webhooks & Events
Overview
Securely handle Replit webhooks with signature validation and replay protection.
Prerequisites
- Replit webhook secret configured
- HTTPS endpoint accessible from internet
- Understanding of cryptographic signatures
- Redis or database for idempotency (optional)
Webhook Endpoint Setup
Express.js
import express from 'express';
import crypto from 'crypto';
const app = express();
// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/replit',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.headers['x-replit-signature'] as string;
const timestamp = req.headers['x-replit-timestamp'] as string;
if (!verifyReplitSignature(req.body, signature, timestamp)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(req.body.toString());
await handleReplitEvent(event);
res.status(200).json({ received: true });
}
);
Signature Verification
function verifyReplitSignature(
payload: Buffer,
signature: string,
timestamp: string
): boolean {
const secret = process.env.REPLIT_WEBHOOK_SECRET!;
// Reject old timestamps (replay attack protection)
const timestampAge = Date.now() - parseInt(timestamp) * 1000;
if (timestampAge > 300000) { // 5 minutes
console.error('Webhook timestamp too old');
return false;
}
// Compute expected signature
const signedPayload = `${timestamp}.${payload.toString()}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
// Timing-safe comparison
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
Event Handler Pattern
type ReplitEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
interface ReplitEvent {
id: string;
type: ReplitEventType;
data: Record<string, any>;
created: string;
}
const eventHandlers: Record<ReplitEventType, (data: any) => Promise<void>> = {
'resource.created': async (data) => { /* handle */ },
'resource.updated': async (data) => { /* handle */ },
'resource.deleted': async (data) => { /* handle */ }
};
async function handleReplitEvent(event: ReplitEvent): Promise<void> {
const handler = eventHandlers[event.type];
if (!handler) {
console.log(`Unhandled event type: ${event.type}`);
return;
}
try {
await handler(event.data);
console.log(`Processed ${event.type}: ${event.id}`);
} catch (error) {
console.error(`Failed to process ${event.type}: ${event.id}`, error);
throw error; // Rethrow to trigger retry
}
}
Idempotency Handling
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
async function isEventProcessed(eventId: string): Promise<boolean> {
const key = `replit:event:${eventId}`;
const exists = await redis.exists(key);
return exists === 1;
}
async function markEventProcessed(eventId: string): Promise<void> {
const key = `replit:event:${eventId}`;
await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
}
Webhook Testing
# Use Replit CLI to send test events
replit webhooks trigger resource.created --url http://localhost:3000/webhooks/replit
# Or use webhook.site for debugging
curl -X POST https://webhook.site/your-uuid \
-H "Content-Type: application/json" \
-d '{"type": "resource.created", "data": {}}'
Instructions
Step 1: Register Webhook Endpoint
Configure your webhook URL in the Replit dashboard.
Step 2: Implement Signature Verification
Use the signature verification code to validate incoming webhooks.
Step 3: Handle Events
Implement handlers for each event type your application needs.
Step 4: Add Idempotency
Prevent duplicate processing with event ID tracking.
Output
- Secure webhook endpoint
- Signature validation enabled
- Event handlers implemented
- Replay attack protection active
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Invalid signature | Wrong secret | Verify webhook secret |
| Timestamp rejected | Clock drift | Check server time sync |
| Duplicate events | Missing idempotency | Implement event ID tracking |
| Handler timeout | Slow processing | Use async queue |
Examples
Testing Webhooks Locally
# Use ngrok to expose local server
ngrok http 3000
# Send test webhook
curl -X POST https://your-ngrok-url/webhooks/replit \
-H "Content-Type: application/json" \
-d '{"type": "test", "data": {}}'
Resources
Next Steps
For performance optimization, see replit-performance-tuning.