Advanced Concepts: Pagination, Filtering, Versioning, and Rate LimitingLesson 5.5

Webhooks and File Uploads in REST APIs

webhooks, webhook design, webhook security, HMAC signature, file upload, multipart form data, Multer, cloud storage, S3 upload, file validation

Webhooks and File Uploads in REST APIs

REST APIs are request-response systems — the client asks, the server answers. But many real-world scenarios require the server to notify the client when something happens asynchronously. Webhooks solve this problem. File uploads are another common REST API requirement that requires special handling.

DiagramWebhook Event Flow

IMAGE PROMPT (replace this block with your generated image):

Flat comparison diagram on white background showing REST vs Webhook patterns. Title: REST Polling vs Webhooks. Top half: Traditional Polling. Client box on left sending five repeated arrows labeled GET /orders/status every 60s to Server box on right. Most arrows show no change response (gray). One shows Order Ready (green). Labeled: Wasteful — 4 of 5 requests return nothing new. Bottom half: Webhook Push. Two actors — Your API Server (left) and Client Webhook URL (right). Timeline: 1. Order placed (event fires in API server). 2. API server immediately sends POST arrow (bold #3A5EFF) to client webhook URL labeled POST /webhook {event: order.created, data: {...}, signature: hmac_sha256}. 3. Client responds 200 OK. Zero polling needed. Horizontal separator between halves. Labels in #3A5EFF. White background.

What Are Webhooks

A webhook is an HTTP POST request sent by your server to a URL provided by the client when a specific event occurs. Instead of the client polling your API every minute to check for new orders, your API sends a POST to the client's webhook URL the moment an order is placed. Webhooks are used by Stripe (payment events), GitHub (repository events), and Twilio (SMS delivery receipts).

Webhook Security with HMAC Signatures

When you send a webhook, sign the payload with HMAC-SHA256 and include the signature in a header. The recipient verifies it to confirm the request came from you and was not tampered with:

const crypto = require('crypto');

const signWebhook = (payload, secret) => {
  return crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
};

const verifyWebhook = (payload, signature, secret) => {
  const expected = signWebhook(payload, secret);
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
};

Always use crypto.timingSafeEqual for signature comparison to prevent timing attacks.

File Uploads with Multer

npm install multer

const upload = multer({
  limits: { fileSize: 5 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    const allowed = ['image/jpeg', 'image/png', 'image/webp'];
    cb(null, allowed.includes(file.mimetype));
  }
});

router.post('/avatar', protect, upload.single('avatar'), uploadAvatar);

Always validate file type by checking the MIME type, not just the file extension. Enforce maximum file size limits. Never store uploaded files on the application server — upload them to cloud storage (AWS S3, Cloudinary) and store only the URL in your database.

Ready to practice?

MCQs · Mini project