{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-echosync-webhooks/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Onboarding & Registration"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"onboarding--registration","__idx":0},"children":["Onboarding & Registration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n A[\"Prepare endpoint,
Signing Secret &
endpoint auth\"] --> B[\"Register
by email\"]\n B --> C[\"Validate test payloads
in testing environment\"]\n C --> D{\"All checks
pass?\"}\n D -- \"No: fix & retest\" --> C\n D -- \"Yes\" --> E[\"Production
activation\"]\n","diagramHtml":"

No: fix & retest

Yes

Prepare endpoint,
Signing Secret &
endpoint auth

Register
by email

Validate test payloads
in testing environment

All checks
pass?

Production
activation

","diagramHtmlDark":"

No: fix & retest

Yes

Prepare endpoint,
Signing Secret &
endpoint auth

Register
by email

Validate test payloads
in testing environment

All checks
pass?

Production
activation

"},"children":["flowchart LR\n A[\"Prepare endpoint,
Signing Secret &
endpoint auth\"] --> B[\"Register
by email\"]\n B --> C[\"Validate test payloads
in testing environment\"]\n C --> D{\"All checks
pass?\"}\n D -- \"No: fix & retest\" --> C\n D -- \"Yes\" --> E[\"Production
activation\"]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before registering, your implementation needs:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTPS with a valid certificate from a trusted Certificate Authority (no self-signed or expired certificates; TLS 1.2+)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Responds within 15 seconds"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}," on success"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Source IP addresses (if you allowlist inbound traffic)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"IP addresses"},"children":["IP addresses"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Active"]}," - all current traffic originates here"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3.19.83.191"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["18.118.90.214"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reserved"]}," - guaranteed, may come into use without notice"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["32.188.140.83"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["35.80.104.162"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Allowlist the reserved pair now, even though it carries no traffic today; doing so prevents interrupted deliveries if Echo begins using it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implementation"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HMAC-SHA256 signature verification (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/echosync-webhooks/technical-implementation"},"children":["Receiving & Verifying Webhooks"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Idempotency handling keyed on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Webhook-Id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Logging of webhook Ids and outcomes for troubleshooting"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Separate testing and production endpoints (required)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example URL"},"children":["Example URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Testing/QA"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api-qa.yourcompany.com/webhooks/echo"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.yourcompany.com/webhooks/echo"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-your-signing-secret","__idx":2},"children":["Step 1: Create Your Signing Secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Specification"},"children":["Specification"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Length"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["24–128 characters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required characters"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least 1 uppercase, 1 lowercase, 1 number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Special characters"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended, not required"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allowed symbols"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"@ # $ % & * ! ? [ ] { } ( ) < > + - _ . , : ; ~ ` ^ | \\ /\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handling guidance"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate it with a cryptographically secure random generator; don't reuse a password or another system's key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store it like any other production credential (secret manager, restricted access)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You may use the same secret for testing and production, or different ones"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Have a plan for rotation if it's ever exposed (contact Technical Integrations to update it)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-choose-endpoint-authentication-optional-recommended","__idx":3},"children":["Step 2: Choose Endpoint Authentication (Optional, Recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Signing Secret proves the request came from Echo, but it doesn't authenticate the request to ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can combine these methods, with one constraint: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only one method can supply the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header"]},". If you configure OAuth, no other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header can be provided: not Basic Auth, and not a custom header by that name. None of these methods replaces the Signing Secret."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-key","__idx":4},"children":["API Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You define a header name and value; Echo sends it with every request."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Configuration"},"children":["Configuration"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header Name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your choice (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-key"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header Value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A key you generate"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-auth","__idx":5},"children":["Basic Auth"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Basic Auth uses the same header-pair mechanism, but the header name is fixed: provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," as the header name and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Basic "]}," as the value, and Echo sends it with every request. Because it occupies the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header, it cannot be combined with OAuth."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oauth-20-client-credentials","__idx":6},"children":["OAuth 2.0 (client credentials)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Echo obtains a bearer token from your token endpoint and sends it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header. Note: the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," below is an OAuth credential for your token endpoint; it is unrelated to your webhook Signing Secret."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your OAuth token endpoint URL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth client identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client_secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth client secret"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["grant_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Space-delimited OAuth scopes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["audience"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Target audience identifier"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How the token flow works is described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/echosync-webhooks/technical-implementation"},"children":["Receiving & Verifying Webhooks"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"custom-headers","__idx":7},"children":["Custom Headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any additional headers you need on every request (routing headers, extra tokens, metadata). Provide them as name/value pairs at registration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-register-by-email","__idx":8},"children":["Step 3: Register by Email"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send your registration to Echo's Technical Integrations team."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email Subject:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Echo Webhook Registration - [Your Company Name]"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required information:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Testing Environment:\n- Webhook URL: https://api-qa.yourcompany.com/webhooks/echo\n- Signing Secret: [Your generated secret]\n\nProduction Environment:\n- Webhook URL: https://api.yourcompany.com/webhooks/echo\n- Signing Secret: [Same or different secret]\n\nContact Information:\n- Primary Contact: [Name and email]\n- Technical Contact: [Name and email, if different]\n- Company: [Your company name]\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Optional endpoint authentication (if applicable):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"API Key:\n- Header Name: [e.g., x-api-key]\n- Header Value: [Your API key]\n\nBasic Auth:\n- Header Name: Authorization\n- Header Value: Basic [base64(username:password)]\n\nOAuth Configuration:\n- Token Endpoint: [Your OAuth endpoint URL]\n- Client ID: [Your client_id]\n- Client Secret: [Your OAuth client_secret]\n- Scope: [If required]\n- Audience: [If required]\n\nCustom Headers:\n- [Header-Name]: [Header-Value]\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Security note:"]}," Follow your organization's practices for sending credentials (encrypted email or secure file sharing if required)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-validate-in-the-testing-environment","__idx":9},"children":["Step 4: Validate in the Testing Environment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Echo registers your testing endpoint first and sends test payloads. Each test payload is a real webhook:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Standard Echo headers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid signature computed with your Signing Secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Webhook-Id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A representative JSON body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your configured endpoint authentication (if any)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To request additional test events later, email Technical Integrations with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subject: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"Echo Webhook Test Events Request\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your registered testing URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your webhook registration Id (from your confirmation email)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Any specific event types you want"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your validation checklist:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the signature:"]}," compute HMAC-SHA256 over the raw request body using your Signing Secret and compare against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Hmac-SHA256"]}," (timing-safe comparison). See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/echosync-webhooks/technical-implementation"},"children":["worked example"]}," with a known secret and expected signature."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify headers:"]}," all Echo headers present, timestamps in UTC ISO 8601; log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Webhook-Id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify response behavior:"]}," success status code (200/202/204) returned within 15 seconds"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify idempotency:"]}," the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Webhook-Id"]}," delivered twice is processed once"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify endpoint auth:"]}," your configured API key / OAuth token / custom headers arrive as expected (if configured)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"common-validation-issues","__idx":10},"children":["Common Validation Issues"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Signature mismatch"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Computing the HMAC over parsed/re-serialized JSON instead of the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw request body"]}," (this is the most common cause)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wrong secret (it's case-sensitive) or stray whitespace in the stored value"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wrong algorithm: must be HMAC-SHA256, base64-encoded"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Character encoding issues in the body or secret"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSL/TLS failures"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Expired, self-signed, or domain-mismatched certificate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Server TLS misconfiguration"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Timeouts"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Processing synchronously before responding: acknowledge first, process in the background"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Slow downstream calls (database, external APIs) blocking the response"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-go-to-production","__idx":11},"children":["Step 5: Go to Production"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When testing is complete:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Email Technical Integrations with your results, including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Echo-Webhook-Id"]}," values of successfully processed test events and any issues you hit and resolved"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request production activation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Echo registers your production endpoint and confirms by email; live events begin flowing"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before requesting activation, confirm your production endpoint is separate from testing, scaled appropriately, and monitored (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/echosync-webhooks/reliability"},"children":["Delivery, Retries & Health"]}," for what to monitor and why)."]}]},"headings":[{"value":"Onboarding & Registration","id":"onboarding--registration","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Create Your Signing Secret","id":"step-1-create-your-signing-secret","depth":2},{"value":"Step 2: Choose Endpoint Authentication (Optional, Recommended)","id":"step-2-choose-endpoint-authentication-optional-recommended","depth":2},{"value":"API Key","id":"api-key","depth":3},{"value":"Basic Auth","id":"basic-auth","depth":3},{"value":"OAuth 2.0 (client credentials)","id":"oauth-20-client-credentials","depth":3},{"value":"Custom Headers","id":"custom-headers","depth":3},{"value":"Step 3: Register by Email","id":"step-3-register-by-email","depth":2},{"value":"Step 4: Validate in the Testing Environment","id":"step-4-validate-in-the-testing-environment","depth":2},{"value":"Common Validation Issues","id":"common-validation-issues","depth":3},{"value":"Step 5: Go to Production","id":"step-5-go-to-production","depth":2}],"frontmatter":{"id":"getting-started","title":"Onboarding & Registration","seo":{"title":"Onboarding & Registration"}},"lastModified":"2026-08-14T20:20:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/echosync-webhooks/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}