Echo delivers shipment events to your HTTPS endpoint as HTTP POST requests with JSON payloads. Every request is signed with HMAC-SHA256 so you can verify it genuinely came from Echo.
Echo publishes two webhook event types. Which you receive depends on your role with Echo:
| Event | Who receives it | What it delivers |
|---|---|---|
| Load Tracking / Status Update | Customers (shippers) | Status and geo-location tracking events for your loads |
| Available Load Notification | Carriers | Loads available for booking (posted, updated, and cancelled) |
Everything in these pages, including registration, security, delivery, and retries, works identically for both; full payload schemas are in the API Reference.
Webhook security involves two independent mechanisms, and you create both:
- A required Signing Secret that Echo signs payloads with so you can verify them.
- Optional but recommended endpoint authentication that Echo presents so your endpoint accepts the request.
Each protects something different; understanding the difference is the single most important part of onboarding.
| Signing Secret | Endpoint Authentication | |
|---|---|---|
| Required? | Yes: every webhook integration must have one | Optional, but strongly recommended |
| Who creates it | You do. You invent the value and give it to Echo during registration. Echo never assigns it. | You do. You give Echo the credentials your endpoint expects. |
| What it does | Echo signs every payload with it. You recompute the signature to prove the request came from Echo and wasn't tampered with. | Echo presents these credentials so your endpoint (or gateway) will accept the inbound request. |
| How it's used | HMAC-SHA256 signature in the X-Echo-Hmac-SHA256 header | API key header, Basic Auth, OAuth 2.0 bearer token, and/or custom headers |
Common mistake: configuring an API key or OAuth and skipping the Signing Secret. They are not alternatives: endpoint authentication gets Echo's request through your front door, while the Signing Secret is how you verify who sent it. The Signing Secret is always required.
Naming notes: Earlier versions of this documentation called the Signing Secret the "Client Secret." It is the same thing. It is not related to the
client_secretfield in an OAuth 2.0 configuration; that is a separate credential you may optionally provide for endpoint authentication.
| Step | What happens |
|---|---|
| 1. Prepare | Stand up an HTTPS endpoint, create your Signing Secret, and decide on optional endpoint authentication. |
| 2. Register | Email your details to Echo's Technical Integrations team. |
| 3. Validate | Echo sends test payloads to your testing endpoint; you verify signatures and responses. |
| 4. Go live | After successful validation, Echo activates your production endpoint. |
The full walkthrough is in Onboarding & Registration.
| Page | What it covers |
|---|---|
| Onboarding & Registration | Prerequisites, creating your Signing Secret, registration, validation testing, going to production |
| Receiving & Verifying Webhooks | What a request looks like, verifying the signature (with code examples), endpoint authentication, implementation best practices |
| Delivery, Retries & Health | Retry schedule, failure threshold, deregistration, monitoring |
| Quick Reference | All technical specifications on one page |
| API Reference | Full webhook payload schemas |
Contact Echo's Technical Integrations team with:
- The
X-Echo-Webhook-Idvalues from your logs - Relevant timestamps and error details
- A clear description of the issue