Skip to main content
Two different problems, two different mechanisms. Idempotency makes a retry safe. If-Match makes a concurrent change safe.

​
Idempotency

Retry safety is handled for you. DropHub derives the key from a value you already send: Keys are scoped to your merchant account, so two calls naming the same order are one submission.

​
Replay semantics

Reusing an order number with a changed payload is a conflict, not an update. If you genuinely want a different shipment, give it a different reference.

​
Bringing your own key

Send Idempotency-Key only if you want to control the replay window yourself. An explicit key always wins over the derived one.
The key is 16–128 characters. Derive it from the business intent that must happen at most once — do not generate a fresh random key on each retry, which is precisely the case idempotency exists to prevent.

​
ETags and If-Match

Your webhook carries a strong numeric entity tag matching ^"[0-9]+"$, quotes included. It is the endpoint’s version in ETag form. A conditional request is required for all three ways of changing it:
  • PATCH /v2/external/webhook
  • DELETE /v2/external/webhook
  • POST /v2/external/webhook/secret-rotations

​
The two failure modes

Never work around a 412 by fetching the current ETag and immediately resubmitting the same change. That defeats the check. Re-read, decide whether your change still makes sense against the new state, and only then retry.

​
Reading the current tag

The ETag comes back on the representation you read and on the response to a successful change — so a sequence of updates can use each response’s tag for the next call without an extra GET.