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:
- Accept
POSTrequests - Return a
200status code within 5 seconds - 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-Signatureheader 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
- Respond quickly - Return 2xx within 10 seconds
- Process asynchronously - Don’t block the response
- Verify signatures - Always check
X-WhereParcel-Signature - Handle duplicates - Use idempotency keys
- 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 →