Webhook Best Practices for Parcel Tracking

Webhooks allow your application to receive real-time updates when a parcel’s status changes. Instead of polling the API repeatedly, you can sit back and let the updates come to you.

Why Use Webhooks?

  • Real-time updates - Know the moment a parcel status changes
  • Reduced API calls - No need to poll every few minutes
  • Better user experience - Notify your customers instantly
  • Cost efficient - Lower API usage means lower costs

Setting Up Your Webhook Endpoint

Your webhook endpoint needs to:

  1. Accept POST requests
  2. Return a 200 status code within 5 seconds
  3. Handle duplicate events gracefully
// Express.js example
app.post('/webhooks/whereparcel', (req, res) => {
  const { event, data } = req.body;

  // Always respond quickly
  res.status(200).json({ received: true });

  // Process the event asynchronously
  processTrackingEvent(event, data);
});

Security: Verifying Webhook Signatures

Every webhook request includes an X-Webhook-Signature header. Always verify this signature to ensure the request came from WhereParcel:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Handling Failures

If your endpoint is unavailable, WhereParcel will retry with exponential backoff:

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry12 hours

After 5 failed attempts, the webhook is marked as failed and you’ll receive an email notification.

Best Practices Summary

  1. Respond quickly - Return 200 within 5 seconds
  2. Process asynchronously - Don’t block the response
  3. Verify signatures - Always check X-Webhook-Signature
  4. Handle duplicates - Use idempotency keys
  5. Monitor your endpoint - Set up alerts for failures

For more details, check our Webhook API documentation.