Skip to main content

Webhooks Overview

Tower Crown pushes real-time HTTP notifications to your server whenever something meaningful happens in your workspace.a shipment is booked, a delivery is completed, or your wallet is funded. You register a single HTTPS endpoint and subscribe to the events you care about.

How Delivery Works​

  1. An event occurs in your workspace (e.g. a shipment is created).
  2. Tower Crown serializes the relevant data into a JSON payload.
  3. The payload is signed with your workspace's unique signing secret using HMAC-SHA256.
  4. An HTTP POST request is sent to your registered endpoint within 2 seconds. We include the signature and event type as request headers.
  5. Your server processes the payload and responds with any 2xx status code to acknowledge receipt.

Request Headers​

Every webhook delivery includes these headers:

HeaderDescription
X-Towercrown-EventThe event identifier (e.g. shipment.created).
X-Towercrown-SignatureHMAC-SHA256 signature in the format t=<timestamp>,v1=<hex>.
X-Towercrown-ReplayPresent and set to "true" only when manually replayed from the console.

Delivery Timeouts & Failures​

Tower Crown's webhook dispatcher has a 2-second timeout per delivery attempt. If your server does not respond in time, or returns a non-2xx status, the attempt is marked as failed and recorded in the delivery log. It is not automatically retried. you can trigger a manual replay from the console.

Best Practices​

  • Use HTTPS. only register https:// endpoints. Plain http:// is accepted in Sandbox for local testing.
  • Respond immediately. acknowledge receipt first, then process asynchronously. Slow handlers cause timeouts.
  • Verify signatures. always validate X-Towercrown-Signature before trusting the payload. See Signature Verification.
  • Handle replays idempotently. check the id field of the delivered payload and skip duplicate processing.