Webhooks: signatures, retries, dead letters

HMAC verification done right, the retry ladder, and test-firing your endpoint.

Register

`` curl -X POST "https://trackjet.world/api/v1/webhooks" \ -H "Authorization: Bearer $TRACKJET_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"url":"https://you.example/hook","events":"shipment.status_changed"}' ``

The response includes a one-time secret — store it now; it signs every delivery to that endpoint. URLs must be public HTTPS (private/internal targets are rejected at registration — SSRF guard).

Verify signatures (do not skip this)

Every delivery carries X-TrackJet-Signature: sha256=<hmac> over the raw request body:

`` expected = "sha256=" + hmac_sha256(raw_body, your_secret) if not constant_time_equals(expected, header): reject(401) ``

Compute over the raw bytes before any JSON parsing, and compare in constant time.

Delivery semantics

Retries: failed deliveries retry with exponential backoff; persistent failures park in a dead-letter queue that is redriven on a schedule with the same signed bytes (your verification still passes on replays).
Auto-disable: an endpoint that keeps failing is disabled with its failure count, instead of being hammered forever.
Ordering: deliveries are near-real-time but not guaranteed ordered — treat the payload's occurred_at as the truth, not arrival order.

Test-fire before you ship

`` curl -X POST "https://trackjet.world/api/v1/webhooks/<id>/test" \ -H "Authorization: Bearer $TRACKJET_API_KEY" ``

Sends one clearly-marked sandbox.test event through the real pipeline — same signature header, same retry path — so you can verify your receiver end-to-end without waiting for a real status change.