Webhook

How Does Webhook Work?

Webhooks work on a simple event-listener model applied to HTTP. You register a URL (your "webhook endpoint") with the sending service, and that service makes an HTTP POST request to your URL whenever the specified event occurs. The request body typically contains a JSON payload describing what happened — for example, a form submission's field values, or a payment's status.

On the receiving end, your server must respond quickly with a 2xx HTTP status code to acknowledge receipt. If your endpoint does not respond in time (usually within 5–30 seconds), the sending service will retry the webhook, often with exponential backoff. This means your webhook handler should do minimal processing synchronously — ideally just enqueue the event payload for asynchronous processing.

Security is critical for webhooks. Reputable services sign their webhook payloads using HMAC-SHA256 with a shared secret. Your endpoint must verify this signature before processing the payload to prevent spoofed requests. Always use HTTPS for webhook endpoints and validate the Content-Type header.

// Express.js webhook endpoint example
import crypto from 'crypto';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook/form-submission', (req, res) => {
  const signature = req.headers['x-widgetjar-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  // Verify HMAC signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(req.body);
  const expectedSig = 'sha256=' + hmac.digest('hex');

  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  )) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());
  // Process event asynchronously
  processEvent(event).catch(console.error);

  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
});

Why Use Webhook?

Advantages of webhooks: Webhooks are dramatically more efficient than polling. Instead of making hundreds of API calls per hour to check for updates, your server receives data exactly when it is needed. This reduces latency (real-time notifications vs. polling intervals), cuts API rate limit consumption, and simplifies your integration code.

When webhooks are tricky: Webhook delivery is not guaranteed — if your server is down, you may miss events unless the sender retries. Duplicate delivery is also possible (retry logic can send the same event twice), so your handler should be idempotent. Debugging webhooks in local development requires a tunnel tool like ngrok to expose your localhost to the internet.

Related Terms