whereparcel

Stuck on integration? Have a question? The developer is standing by.

Guide 10 min read

Webhook Best Practices for Parcel Tracking

Learn how to set up reliable webhook endpoints for automatic parcel tracking notifications with WhereParcel.

WhereParcel Team

Webhooks let your application receive parcel status updates without polling. After you register a parcel, WhereParcel re-checks it about every 12 hours until it is delivered (for up to 10 days) and sends the latest status to your endpoint after every check.

Why Use Webhooks?

  • Automatic updates - Every subscribed parcel is re-checked about every 12 hours, with no polling code on your side
  • Reduced API calls - Registering a parcel counts once; every check after that is free
  • Better user experience - Pass status changes on to your customers automatically
  • 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-WhereParcel-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

Each webhook is delivered once. There are no automatic retries.

If your endpoint does not return a 2xx status within 10 seconds — or is unreachable because of a DNS, TLS, or connection error — that delivery is dropped and the notification is not resent.

This makes endpoint availability your responsibility. A few things that help:

  • Return 2xx immediately, then process in the background. Don’t do slow work (database writes, third-party calls) before responding.
  • Don’t put authentication in front of your webhook URL. Requests carry the X-WhereParcel-Signature header for verification, not a bearer token — an endpoint behind auth will reject every delivery with 401.
  • Keep the URL alive. If you retire the host or let the domain lapse, deliveries fail silently on our side.
  • Reconcile with the API. For anything you must not miss, poll GET /v2/webhooks/subscriptions/{requestId} to confirm the current state rather than relying on the webhook alone.

Best Practices Summary

  1. Respond quickly - Return 2xx within 10 seconds
  2. Process asynchronously - Don’t block the response
  3. Verify signatures - Always check X-WhereParcel-Signature
  4. Handle duplicates - Use idempotency keys
  5. Monitor your endpoint - Deliveries are not retried, so downtime means lost notifications

For more details, check our API documentation.

Can't find your carrier? We add new carriers on request — just let us know.

Request a carrier →

Got a question? Just ask. Drop by our Discord — the developer behind WhereParcel reads every message and replies personally. No bots, no tickets, just a real conversation.

Join Discord → Join Slack →

Tags: #webhooks #best-practices #notifications