Webhook Patterns & Best Practices

Build reliable event-driven workflows. Learn proven patterns for webhook security, error handling, and scalability.

12 min readIntermediateLast updated: December 2024

6 Essential Webhook Patterns

Implement these patterns to build webhook integrations that are secure, reliable, and maintainable.

Signature Verification

Always verify webhook signatures to ensure requests come from legitimate sources. Most services sign payloads with HMAC-SHA256.

// Verify webhook signature
const signature = request.headers['x-signature'];
const payload = JSON.stringify(request.body);
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Key Points:

Store webhook secrets in environment variables
Use constant-time comparison to prevent timing attacks
Log failed verification attempts for security monitoring

Idempotency Handling

Webhooks may be delivered multiple times. Use idempotency keys to ensure each event is processed only once.

// Check if event already processed
const eventId = request.body.id;
const processed = await db.webhookEvents.findOne({ eventId });

if (processed) {
  return { status: 'already_processed' };
}

// Process event and store ID
await processEvent(request.body);
await db.webhookEvents.create({ eventId, processedAt: new Date() });

Key Points:

Store event IDs with TTL for automatic cleanup
Return 200 even for duplicate events to prevent retries
Include idempotency key in your processing logic

Async Processing

Respond quickly to webhook requests (within 30 seconds) by queuing work for background processing.

// Respond immediately, process later
app.post('/webhook', async (req, res) => {
  // Validate quickly
  if (!isValidSignature(req)) {
    return res.status(401).send('Invalid');
  }

  // Queue for background processing
  await queue.add('process-webhook', {
    payload: req.body,
    receivedAt: Date.now()
  });

  // Respond immediately
  res.status(200).send('Accepted');
});

Key Points:

Most services timeout after 30 seconds
Use message queues (Redis, SQS, etc.) for reliability
Implement dead letter queues for failed jobs

Payload Validation

Validate webhook payloads against expected schemas to catch malformed data early and prevent downstream errors.

// Validate payload structure
const schema = z.object({
  event: z.enum(['created', 'updated', 'deleted']),
  data: z.object({
    id: z.string(),
    timestamp: z.string().datetime(),
    attributes: z.record(z.unknown())
  })
});

const result = schema.safeParse(request.body);
if (!result.success) {
  console.error('Invalid payload:', result.error);
  return res.status(400).send('Invalid payload');
}

Key Points:

Use Zod, Joi, or similar for schema validation
Log validation failures for debugging
Be lenient with unknown fields for forward compatibility

Retry Logic & Backoff

When sending webhooks, implement exponential backoff to handle temporary failures gracefully.

// Exponential backoff for retries
async function sendWithRetry(url, payload, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        body: JSON.stringify(payload),
        headers: { 'Content-Type': 'application/json' }
      });

      if (response.ok) return response;
      if (response.status < 500) throw new Error('Client error');
    } catch (error) {
      const delay = Math.pow(2, attempt) * 1000;
      await sleep(delay);
    }
  }
  throw new Error('Max retries exceeded');
}

Key Points:

Start with short delays (1s, 2s, 4s, 8s, 16s)
Add jitter to prevent thundering herd
Set maximum retry limits and alert on failures

Secret Rotation

Rotate webhook secrets periodically. Support multiple active secrets during rotation windows.

// Support multiple secrets during rotation
const secrets = [
  process.env.WEBHOOK_SECRET_CURRENT,
  process.env.WEBHOOK_SECRET_PREVIOUS
].filter(Boolean);

function verifySignature(payload, signature) {
  for (const secret of secrets) {
    const expected = computeSignature(payload, secret);
    if (timingSafeEqual(signature, expected)) {
      return true;
    }
  }
  return false;
}

Key Points:

Rotate secrets every 90 days minimum
Support 2 active secrets during transition
Automate rotation with secret management tools

Common Webhook Use Cases

Real-world scenarios where webhooks power critical automations.

Payment Processing

Handle Stripe/PayPal payment events

payment.succeededpayment.failedrefund.created

CI/CD Pipelines

Trigger builds on code pushes

pushpull_requestdeployment

CRM Sync

Keep systems in sync on contact changes

contact.createddeal.updatedactivity.logged

E-commerce

React to order lifecycle events

order.placedorder.shippedinventory.low

What's Next?

Visual Debugging

Debug webhook workflows with visual execution traces

Export to Code

Export your webhook workflows as production TypeScript

Frequently Asked Questions

Common questions about webhook implementations.

Ready to Build Event-Driven Workflows?

Create webhook-triggered automations with visual debugging and built-in best practices.

Start Free Browse Templates

Webhook Patterns & Best Practices

Build reliable event-driven workflows. Learn proven patterns for webhook security, error handling, and scalability.

Start Building

12 min readIntermediateLast updated: December 2024

6 Essential Webhook Patterns

Implement these patterns to build webhook integrations that are secure, reliable, and maintainable.

Signature Verification

Always verify webhook signatures to ensure requests come from legitimate sources. Most services sign payloads with HMAC-SHA256.

// Verify webhook signature
const signature = request.headers['x-signature'];
const payload = JSON.stringify(request.body);
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Key Points:

Store webhook secrets in environment variables
Use constant-time comparison to prevent timing attacks
Log failed verification attempts for security monitoring

Idempotency Handling

Webhooks may be delivered multiple times. Use idempotency keys to ensure each event is processed only once.

// Check if event already processed
const eventId = request.body.id;
const processed = await db.webhookEvents.findOne({ eventId });

if (processed) {
  return { status: 'already_processed' };
}

// Process event and store ID
await processEvent(request.body);
await db.webhookEvents.create({ eventId, processedAt: new Date() });

Key Points:

Store event IDs with TTL for automatic cleanup
Return 200 even for duplicate events to prevent retries
Include idempotency key in your processing logic

Async Processing

Respond quickly to webhook requests (within 30 seconds) by queuing work for background processing.

// Respond immediately, process later
app.post('/webhook', async (req, res) => {
  // Validate quickly
  if (!isValidSignature(req)) {
    return res.status(401).send('Invalid');
  }

  // Queue for background processing
  await queue.add('process-webhook', {
    payload: req.body,
    receivedAt: Date.now()
  });

  // Respond immediately
  res.status(200).send('Accepted');
});

Key Points:

Most services timeout after 30 seconds
Use message queues (Redis, SQS, etc.) for reliability
Implement dead letter queues for failed jobs

Payload Validation

Validate webhook payloads against expected schemas to catch malformed data early and prevent downstream errors.

// Validate payload structure
const schema = z.object({
  event: z.enum(['created', 'updated', 'deleted']),
  data: z.object({
    id: z.string(),
    timestamp: z.string().datetime(),
    attributes: z.record(z.unknown())
  })
});

const result = schema.safeParse(request.body);
if (!result.success) {
  console.error('Invalid payload:', result.error);
  return res.status(400).send('Invalid payload');
}

Key Points:

Use Zod, Joi, or similar for schema validation
Log validation failures for debugging
Be lenient with unknown fields for forward compatibility

Retry Logic & Backoff

When sending webhooks, implement exponential backoff to handle temporary failures gracefully.

// Exponential backoff for retries
async function sendWithRetry(url, payload, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        body: JSON.stringify(payload),
        headers: { 'Content-Type': 'application/json' }
      });

      if (response.ok) return response;
      if (response.status < 500) throw new Error('Client error');
    } catch (error) {
      const delay = Math.pow(2, attempt) * 1000;
      await sleep(delay);
    }
  }
  throw new Error('Max retries exceeded');
}

Key Points:

Start with short delays (1s, 2s, 4s, 8s, 16s)
Add jitter to prevent thundering herd
Set maximum retry limits and alert on failures

Secret Rotation

Rotate webhook secrets periodically. Support multiple active secrets during rotation windows.

// Support multiple secrets during rotation
const secrets = [
  process.env.WEBHOOK_SECRET_CURRENT,
  process.env.WEBHOOK_SECRET_PREVIOUS
].filter(Boolean);

function verifySignature(payload, signature) {
  for (const secret of secrets) {
    const expected = computeSignature(payload, secret);
    if (timingSafeEqual(signature, expected)) {
      return true;
    }
  }
  return false;
}

Key Points:

Rotate secrets every 90 days minimum
Support 2 active secrets during transition
Automate rotation with secret management tools

Common Webhook Use Cases

Real-world scenarios where webhooks power critical automations.

Payment Processing

Handle Stripe/PayPal payment events

payment.succeededpayment.failedrefund.created

CI/CD Pipelines

Trigger builds on code pushes

pushpull_requestdeployment

CRM Sync

Keep systems in sync on contact changes

contact.createddeal.updatedactivity.logged

E-commerce

React to order lifecycle events

order.placedorder.shippedinventory.low

What's Next?

Visual Debugging

Debug webhook workflows with visual execution traces

Export to Code

Export your webhook workflows as production TypeScript

Frequently Asked Questions

Common questions about webhook implementations.

Ready to Build Event-Driven Workflows?

Create webhook-triggered automations with visual debugging and built-in best practices.

Start Free Browse Templates

Webhook Patterns & Best Practices

6 Essential Webhook Patterns

Signature Verification

Key Points:

Idempotency Handling

Key Points:

Async Processing

Key Points:

Payload Validation

Key Points:

Retry Logic & Backoff

Key Points:

Secret Rotation

Key Points:

Common Webhook Use Cases

Payment Processing

CI/CD Pipelines

CRM Sync

E-commerce

What's Next?

Visual Debugging

Export to Code

Frequently Asked Questions

How do I debug webhook issues?

What should I return from a webhook endpoint?

How do I handle webhook ordering?

Should I use webhook or polling for integrations?

How do I secure my webhook endpoint?

Ready to Build Event-Driven Workflows?

Webhook Patterns & Best Practices

6 Essential Webhook Patterns

Signature Verification

Key Points:

Idempotency Handling

Key Points:

Async Processing

Key Points:

Payload Validation

Key Points:

Retry Logic & Backoff

Key Points:

Secret Rotation

Key Points:

Common Webhook Use Cases

Payment Processing

CI/CD Pipelines

CRM Sync

E-commerce

What's Next?

Visual Debugging

Export to Code

Frequently Asked Questions

How do I debug webhook issues?

What should I return from a webhook endpoint?

How do I handle webhook ordering?

Should I use webhook or polling for integrations?

How do I secure my webhook endpoint?

Ready to Build Event-Driven Workflows?

Webhook Patterns & Best Practices

6 Essential Webhook Patterns

Signature Verification

Key Points:

Idempotency Handling

Key Points:

Async Processing

Key Points:

Payload Validation

Key Points:

Retry Logic & Backoff

Key Points:

Secret Rotation

Key Points:

Common Webhook Use Cases

Payment Processing

CI/CD Pipelines

CRM Sync

E-commerce

What's Next?

Visual Debugging

Export to Code