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.

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:

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)
• 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.

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.

Allowed symbols

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

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)

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.

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

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.

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.

How the token flow works is described in Receiving & Verifying Webhooks.

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

Send your registration to Echo's Technical Integrations team.

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

Required information:

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):

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).

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 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)

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

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 for what to monitor and why).