# Onboarding & Registration

Registration is an email-based process with Echo's Technical Integrations team: you prepare an endpoint and credentials, register, validate against test payloads in the testing environment, then go live in production.

```mermaid
flowchart LR
    A["Prepare endpoint,<br/>Signing Secret &<br/>endpoint auth"] --> B["Register<br/>by email"]
    B --> C["Validate test payloads<br/>in testing environment"]
    C --> D{"All checks<br/>pass?"}
    D -- "No: fix & retest" --> C
    D -- "Yes" --> E["Production<br/>activation"]
```

## Prerequisites

Before registering, your implementation needs:

**Endpoint**

- HTTPS with a valid certificate from a trusted Certificate Authority (no self-signed or expired certificates; TLS 1.2+)
- Responds within 15 seconds
- Returns `200 OK`, `202 Accepted`, or `204 No Content` on success


**Source IP addresses (if you allowlist inbound traffic)**

Echo delivers all webhooks from static egress IP addresses that are guaranteed not to change. If your endpoint or gateway restricts inbound traffic by IP, allowlist all four:

| Status | IP addresses |
|  --- | --- |
| **Active** - all current traffic originates here | `3.19.83.191``18.118.90.214` |
| **Reserved** - guaranteed, may come into use without notice | `32.188.140.83``35.80.104.162` |


Allowlist the reserved pair now, even though it carries no traffic today; doing so prevents interrupted deliveries if Echo begins using it.

**Implementation**

- HMAC-SHA256 signature verification (see [Receiving & Verifying Webhooks](/echosync-webhooks/technical-implementation))
- Idempotency handling keyed on `X-Echo-Webhook-Id`
- Logging of webhook Ids and outcomes for troubleshooting


**Separate testing and production endpoints (required)**

You must register two different URLs: one for testing, one for production. Echo validates your integration against the testing endpoint before any production traffic flows.

| Environment | Example URL |
|  --- | --- |
| Testing/QA | `https://api-qa.yourcompany.com/webhooks/echo` |
| Production | `https://api.yourcompany.com/webhooks/echo` |


## Step 1: Create Your Signing Secret

**You create the Signing Secret; Echo does not assign one to you.** Generate a random value, store it securely on your side, and provide it to Echo during registration. Echo uses it to sign every webhook payload; you use it to verify each payload came from Echo.

| Requirement | Specification |
|  --- | --- |
| **Length** | 24–128 characters |
| **Required characters** | At least 1 uppercase, 1 lowercase, 1 number |
| **Special characters** | Recommended, not required |


**Allowed symbols**

```text
@ # $ % & * ! ? [ ] { } ( ) < > + - _ . , : ; ~ ` ^ | \ /
```

**Handling guidance**

- Generate it with a cryptographically secure random generator; don't reuse a password or another system's key
- Store it like any other production credential (secret manager, restricted access)
- You may use the same secret for testing and production, or different ones
- Have a plan for rotation if it's ever exposed (contact Technical Integrations to update it)


## Step 2: Choose Endpoint Authentication (Optional, Recommended)

The Signing Secret proves the request came from Echo, but it doesn't authenticate the request to *your* infrastructure. If your endpoint or API gateway requires inbound credentials, provide them at registration and Echo will present them with every request. Most partner gateways expect this; configuring it prevents rejected deliveries on your side.

You can combine these methods, with one constraint: **only one method can supply the `Authorization` header**. If you configure OAuth, no other `Authorization` header can be provided: not Basic Auth, and not a custom header by that name. None of these methods replaces the Signing Secret.

### API Key

You define a header name and value; Echo sends it with every request.

| Configuration | Notes |
|  --- | --- |
| **Header Name** | Your choice (e.g., `x-api-key`, `api-key`) |
| **Header Value** | A key you generate |


### Basic Auth

Basic Auth uses the same header-pair mechanism, but the header name is fixed: provide `Authorization` as the header name and `Basic <base64(username:password)>` as the value, and Echo sends it with every request. Because it occupies the `Authorization` header, it cannot be combined with OAuth.

### OAuth 2.0 (client credentials)

Echo obtains a bearer token from your token endpoint and sends it in the `Authorization` header. Note: the `client_secret` below is an OAuth credential for your token endpoint; it is unrelated to your webhook Signing Secret.

| Field | Required | Notes |
|  --- | --- | --- |
| **endpoint** | Yes | Your OAuth token endpoint URL |
| **client_id** | Yes | OAuth client identifier |
| **client_secret** | Yes | OAuth client secret |
| **grant_type** | Yes | Always `client_credentials` |
| **scope** | No | Space-delimited OAuth scopes |
| **audience** | No | Target audience identifier |


How the token flow works is described in [Receiving & Verifying Webhooks](/echosync-webhooks/technical-implementation).

### Custom Headers

Any additional headers you need on every request (routing headers, extra tokens, metadata). Provide them as name/value pairs at registration.

## Step 3: Register by Email

Send your registration to Echo's Technical Integrations team.

**Email Subject:** `Echo Webhook Registration - [Your Company Name]`

**Required information:**

```text
Testing Environment:
- Webhook URL: https://api-qa.yourcompany.com/webhooks/echo
- Signing Secret: [Your generated secret]

Production Environment:
- Webhook URL: https://api.yourcompany.com/webhooks/echo
- Signing Secret: [Same or different secret]

Contact Information:
- Primary Contact: [Name and email]
- Technical Contact: [Name and email, if different]
- Company: [Your company name]
```

**Optional endpoint authentication (if applicable):**

```text
API Key:
- Header Name: [e.g., x-api-key]
- Header Value: [Your API key]

Basic Auth:
- Header Name: Authorization
- Header Value: Basic [base64(username:password)]

OAuth Configuration:
- Token Endpoint: [Your OAuth endpoint URL]
- Client ID: [Your client_id]
- Client Secret: [Your OAuth client_secret]
- Scope: [If required]
- Audience: [If required]

Custom Headers:
- [Header-Name]: [Header-Value]
```

**Security note:** Follow your organization's practices for sending credentials (encrypted email or secure file sharing if required).

## Step 4: Validate in the Testing Environment

Echo registers your testing endpoint first and sends test payloads. Each test payload is a real webhook:

- Standard Echo headers
- A valid signature computed with your Signing Secret
- A unique `X-Echo-Webhook-Id`
- A representative JSON body
- Your configured endpoint authentication (if any)


To request additional test events later, email Technical Integrations with:

- Subject: **"Echo Webhook Test Events Request"**
- Your registered testing URL
- Your webhook registration Id (from your confirmation email)
- Any specific event types you want


**Your validation checklist:**

- **Verify the signature:** compute HMAC-SHA256 over the raw request body using your Signing Secret and compare against `X-Echo-Hmac-SHA256` (timing-safe comparison). See the [worked example](/echosync-webhooks/technical-implementation) with a known secret and expected signature.
- **Verify headers:** all Echo headers present, timestamps in UTC ISO 8601; log the `X-Echo-Webhook-Id`
- **Verify response behavior:** success status code (200/202/204) returned within 15 seconds
- **Verify idempotency:** the same `X-Echo-Webhook-Id` delivered twice is processed once
- **Verify endpoint auth:** your configured API key / OAuth token / custom headers arrive as expected (if configured)


### Common Validation Issues

**Signature mismatch**

- Computing the HMAC over parsed/re-serialized JSON instead of the **raw request body** (this is the most common cause)
- Wrong secret (it's case-sensitive) or stray whitespace in the stored value
- Wrong algorithm: must be HMAC-SHA256, base64-encoded
- Character encoding issues in the body or secret


**SSL/TLS failures**

- Expired, self-signed, or domain-mismatched certificate
- Server TLS misconfiguration


**Timeouts**

- Processing synchronously before responding: acknowledge first, process in the background
- Slow downstream calls (database, external APIs) blocking the response


## Step 5: Go to Production

When testing is complete:

1. Email Technical Integrations with your results, including the `X-Echo-Webhook-Id` values of successfully processed test events and any issues you hit and resolved
2. Request production activation
3. Echo registers your production endpoint and confirms by email; live events begin flowing


Before requesting activation, confirm your production endpoint is separate from testing, scaled appropriately, and monitored (see [Delivery, Retries & Health](/echosync-webhooks/reliability) for what to monitor and why).