# Echo Webhooks

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.

## Webhook Event Types

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.

## The Two Secrets You Provide: Read This First

Webhook security involves two independent mechanisms, and you create both:

1. A required **Signing Secret** that Echo signs payloads with so you can verify them.
2. 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_secret` field in an OAuth 2.0 configuration; that is a separate credential you may optionally provide for endpoint authentication.


## How Onboarding Works

| 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](/echosync-webhooks/getting-started).

## Documentation Map

| Page | What it covers |
|  --- | --- |
| [Onboarding & Registration](/echosync-webhooks/getting-started) | Prerequisites, creating your Signing Secret, registration, validation testing, going to production |
| [Receiving & Verifying Webhooks](/echosync-webhooks/technical-implementation) | What a request looks like, verifying the signature (with code examples), endpoint authentication, implementation best practices |
| [Delivery, Retries & Health](/echosync-webhooks/reliability) | Retry schedule, failure threshold, deregistration, monitoring |
| [Quick Reference](/echosync-webhooks/quick-reference) | All technical specifications on one page |
| API Reference | Full webhook payload schemas |


## Getting Support

Contact Echo's Technical Integrations team with:

- The `X-Echo-Webhook-Id` values from your logs
- Relevant timestamps and error details
- A clear description of the issue