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-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.