Skip to main content

Webhook Integration Guide

Connect Oto with your CRM or automation platform to receive real-time notifications

Written by Nicole Steininger

Overview

Oto can automatically send data to your systems via webhooks when important events occur. This allows you to:

  • Automatically add leads to your CRM (e.g., Salesforce, HubSpot)

  • Trigger automated follow-up sequences

  • Connect with Zapier, Make, or other automation platforms

  • Send data to your practice management system

Available Events

Event

Description

lead.created

A new patient registered through the provider directory

tfi.completed

A patient completed a TFI assessment (coming soon)

Setting Up Your Webhook

Step 1: Get Your Webhook URL

First, you'll need a webhook URL from your integration platform:

Zapier:

  1. Create a new Zap with "Webhooks by Zapier" as the trigger

  2. Choose "Catch Hook" as the event

  3. Copy the webhook URL provided

Make (formerly Integromat):

  1. Create a new scenario with "Webhooks" as the trigger

  2. Choose "Custom webhook"

  3. Copy the webhook URL provided

Your CRM:

Most modern CRMs support incoming webhooks. Check your CRM's documentation for webhook or API endpoint URLs.

Step 2: Configure in Oto Dashboard

  1. Go to Settings in your Oto provider dashboard

  2. Click on the Integrations tab

  3. Paste your webhook URL in the "Webhook URL" field

  4. Select which events you want to receive

  5. Click Save Webhook Settings

Once saved, Oto will automatically generate a webhook secret for security verification.

Webhook Payload

lead.created

When a new lead registers, we send a POST request with the following JSON payload:

{
  "event": "lead.created",
  "test": true,
  "timestamp": "2026-01-14T12:17:23.884Z",
  "lead": {
    "id": "test_1768393043884",
    "firstName": "Test",
    "lastName": "Lead",
    "email": "[email protected]",
    "phone": "+15551234567",
    "locationId": "test-location",
    "locationName": "Test Location",
    "organisationId": "a9oa94qrADws1qfbNjgk",
    "organisationName": "BLUEMOTH Heari",
    "preferredContactMethod": "email",
    "messageForProvider": "This is a test webhook payload to verify your integration is working correctly.",
    "createdAt": "2026-01-14T12:17:23.885Z",
    "hasHearingLoss": true,
    "usesHearingAids": false,
    "tinnitusDuration": "more_than_2_years",
    "shareActivityData": true
  }
}

Field Reference

Field

Type

Description

event

string

The event type (e.g., "lead.created")

test

boolean

true if sent using the 'test webhook' button

timestamp

string

ISO 8601 timestamp of when the webhook was sent

lead.id

string

Unique identifier for the lead

lead.firstName

string

Patient's first name

lead.lastName

string

Patient's last name

lead.email

string

Patient's email address

lead.phone

string

Patient's phone number

lead.locationId

string

ID of the location they selected

lead.locationName

string

Name of the location they selected

lead.organisationId

string

Your organization's ID

lead.organisationName

string

Your organization's name

lead.preferredContactMethod

string

"email", "phone", or "no_preference"

lead.messageForProvider

string

Optional message from the patient

lead.createdAt

string

When the lead registered

lead.hasHearingLoss

boolean

Whether they reported hearing loss

lead.usesHearingAids

boolean

Whether they use hearing aids

lead.tinnitusDuration

string

How long they've had tinnitus (see values below)

lead.shareActivityData

boolean

Whether they consented to share app activity

Tinnitus Duration Values

  • less_than_6_months - Less than 6 months

  • 6_to_12_months - 6 to 12 months

  • 1_to_2_years - 1 to 2 years

  • more_than_2_years - More than 2 years

Security: Verifying Webhook Signatures

To ensure webhook requests are genuinely from Oto, we sign each request with your webhook secret using HMAC-SHA256. We recommend verifying signatures in production environments.

Headers

Each webhook request includes these headers:

  • X-Oto-Signature - HMAC-SHA256 signature

  • X-Oto-Timestamp - Unix timestamp (milliseconds) when the request was signed

  • Content-Type - Always application/json

Verification Steps

  1. Get the X-Oto-Timestamp header value

  2. Get the raw request body (as a string)

  3. Concatenate: {timestamp}.{body}

  4. Compute HMAC-SHA256 using your webhook secret

  5. Compare with the X-Oto-Signature header

Delivery History

You can view the status of recent webhook deliveries in Settings > Integrations. The delivery history shows:

  • Time the webhook was sent

  • Event type

  • Success or failure status

  • HTTP response code

  • Response time

Zapier Integration Example

Here's how to set up a complete Zapier integration:

  1. Create a new Zap

  2. Trigger: Webhooks by Zapier → Catch Hook

  3. Copy the webhook URL to your Oto dashboard

  4. Test the trigger by registering a test lead

  5. Add an action: Connect to your CRM or email tool

  6. Map the fields:

    • First Name → lead.firstName

    • Last Name → lead.lastName

    • Email → lead.email

    • Phone → lead.phone

    • Notes → lead.messageForProvider

Troubleshooting

Webhook Not Receiving Data

  1. Verify the URL is correct and uses HTTPS

  2. Check that your endpoint is publicly accessible

  3. Check the Delivery History in Settings > Integrations

  4. Make sure the event type is enabled

Signature Verification Failing

  1. Ensure you're using the raw request body, not a parsed/modified version

  2. Check that the timestamp in your calculation matches the header exactly

  3. Verify you're using the correct webhook secret from your dashboard

Missing Fields

Some fields may be null if the patient didn't provide that information during registration. Always check for null values in your integration.

Need Help?

If you're having trouble setting up your webhook integration, contact us at [email protected] and we'll help you get connected.

Did this answer your question?