Best Practices

Use descriptive names

Name your workspaces and endpoints clearly so you can quickly identify them:

Workspace: "E-commerce App - Development"
├── Endpoint: "Stripe Payments"
├── Endpoint: "Shopify Orders"
└── Endpoint: "SendGrid Email Events"

Workspace: "E-commerce App - Staging"
├── Endpoint: "Stripe Payments"
└── Endpoint: "Shopify Orders"

Separate by environment

Create different workspaces for development, staging, and production testing. This keeps your webhook data organized and makes it easy to find relevant requests.

One endpoint per webhook source

Create separate endpoints for each service sending webhooks (Stripe, GitHub, etc.). This makes it easier to filter and find specific webhooks.

Capture real webhooks first

Start by capturing real webhooks from your external services. These become your test fixtures for local development.

Create variations

Use the request editor to create variations of real webhooks:

• Change event types (e.g., payment.succeeded → payment.failed)
• Modify amounts or quantities to test edge cases
• Add or remove fields to test validation
• Send malformed data to test error handling

Save these as versions with descriptive comments for future use.

Test failure scenarios

Don't just test the happy path. Create test cases for:

• Duplicate webhook delivery (same event ID)
• Out-of-order events
• Missing required fields
• Invalid signatures (if applicable)

Return 200 quickly

Webhook providers often have short timeout windows (5-30 seconds). Return a 200 OK immediately and process the webhook asynchronously if needed.

app.post('/webhook', async (req, res) => {
  // Return 200 immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

Handle duplicates (idempotency)

Webhook providers may retry delivery, sending the same event multiple times. Always check if you've already processed an event before taking action.

async function processWebhook(event) {
  // Check if already processed
  const exists = await db.processedEvents.findOne({ eventId: event.id });
  if (exists) {
    console.log(`Event ${event.id} already processed, skipping`);
    return;
  }

  // Process the event
  await handleEvent(event);

  // Mark as processed
  await db.processedEvents.create({ eventId: event.id });
}

Verify webhook signatures

In production, always verify webhook signatures to ensure requests come from the expected source. Most providers include a signature header you can validate.

Log everything

Log incoming webhooks and processing results. This makes debugging much easier when something goes wrong.

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', {
    type: req.body.type,
    id: req.body.id,
    timestamp: new Date().toISOString()
  });

  // ... process webhook

  console.log('Webhook processed:', { id: req.body.id, status: 'success' });
});

• Keep API keys secure: Use environment variables, never commit keys to git
• Use HTTPS: Always use HTTPS URLs for webhook endpoints (HookReplay enforces this)
• Validate input: Never trust webhook data blindly - validate and sanitize
• Limit permissions: Your webhook handler should have minimal database/service permissions