📋JSON Templates

Webhook Event Payload

Standard structure for webhook event payloads with metadata and versioning.

Explanation

Consistent webhook format helps consumers reliably process events with proper metadata.

Examples

User Created Event

Output

{
  "id": "evt_1234567890",
  "type": "user.created",
  "version": "1.0",
  "timestamp": "2024-12-17T10:30:00Z",
  "data": {
    "userId": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "createdAt": "2024-12-17T10:30:00Z"
  },
  "metadata": {
    "environment": "production",
    "source": "api"
  }
}

Payment Success Event

Output

{
  "id": "evt_9876543210",
  "type": "payment.succeeded",
  "version": "1.0",
  "timestamp": "2024-12-17T11:00:00Z",
  "data": {
    "paymentId": "pay_xyz789",
    "amount": 4999,
    "currency": "USD",
    "customerId": "cus_123"
  }
}

Code Examples

TypeScript Handler

interface WebhookPayload<T = any> {
  id: string;
  type: string;
  version: string;
  timestamp: string;
  data: T;
  metadata?: Record<string, any>;
}

// Webhook handler
async function handleWebhook(payload: WebhookPayload) {
  // Verify signature first
  switch (payload.type) {
    case 'user.created':
      await handleUserCreated(payload.data);
      break;
    case 'payment.succeeded':
      await handlePaymentSuccess(payload.data);
      break;
    default:
      console.log(`Unknown event type: ${payload.type}`);
  }
}

Express.js Endpoint

// Express endpoint
app.post('/webhooks', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  // Verify webhook signature
  const isValid = verifySignature(req.body, signature);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  await processWebhook(req.body);
  
  // Return 200 quickly
  res.status(200).json({ received: true });
});

Try it Now

Open in JSON Formatter

💡 Tips

Include unique event ID for deduplication
Use semantic event types (resource.action)
Version your webhook payloads
Add timestamp for ordering events
Include retry metadata for failed deliveries
Return 200 quickly, process async

⚠️ Common Pitfalls

Always verify webhook signatures
Don't include sensitive data in webhooks
Handle idempotency (events may be sent multiple times)
Set reasonable timeout for webhook processing