Skip to content
  • There are no suggestions because the search field is empty.

Webhook Fundamentals

Use this guide to understand how webhooks work, the difference between inbound and outbound webhooks, how authentication is handled, what payloads contain, and how retries work when requests fail.

Webhooks are the foundation of most real-time SalesAi integrations.

What Is a Webhook?

A webhook is a method of sending data from one system to another automatically when an event occurs.

Instead of continuously checking for new data, a webhook pushes information immediately when something happens.

Example

A lead submits a website form:

Website Form → Webhook → SalesAi

The contact information is sent immediately without requiring manual intervention.

Inbound vs Outbound Webhooks

There are two primary webhook types used in SalesAi integrations.

Inbound Webhooks

Inbound webhooks send data into SalesAi.

Common use cases:

  • New lead creation
  • Contact enrollment
  • CRM contact synchronization
  • Form submissions
  • Lead routing
Example:

CRM → SalesAi

The CRM sends contact information to a SalesAi webhook endpoint.

Outbound Webhooks

Outbound webhooks send data out of SalesAi.

Common use cases:

  • Post-call updates
  • CRM updates
  • Call outcome reporting
  • Transcript delivery
  • Activity creation
Example:

SalesAi → CRM

SalesAi sends call results back to another platform after a conversation is completed.

Typical Webhook Flow

Inbound Example

Website Form → CRM → SalesAi

Outbound Example

SalesAi Call Complete → Webhook → CRM Update

Most integrations utilize both inbound and outbound webhooks.

Authentication

Authentication ensures that only authorized systems can send data.

SalesAi inbound webhooks typically use a shared secret header for authentication.

Example Header

Header Name

Purpose

X-SalesAi-Webhook-Shared-Secret

Verifies the sender is authorized

The shared secret configured in the sending application must exactly match the value configured in SalesAi.

Common Authentication Issues

Issue

Resolution

Missing header

Add required authentication header

Incorrect secret

Verify secret value matches

Typographical errors

Remove extra spaces and invalid characters

Wrong header name

Verify header spelling

Authentication failures may prevent requests from being processed.

Understanding Payloads

A payload is the data being sent within the webhook request.

Most modern integrations use JSON payloads.

Example Inbound Payload

{

"first_name": "John",

"last_name": "Smith",

"email": "john@example.com",

"phone_number": "3125551234"

}

Common Payload Components

Field Type

Purpose

Contact Information

Creates or updates contacts

Custom Fields

Additional context

CRM IDs

Record matching

Lead Source

Attribution

Call Results

Post-call updates

The receiving system processes the payload and performs the required action.

Required Fields

SalesAi recommends the following fields for inbound contact creation:

Field

Description

first_name

Contact first name

last_name

Contact last name

email

Contact email

phone_number

Contact phone number

Missing required fields may cause requests to fail.

HTTP Response Codes

When a webhook is received, the destination system returns a response code.

Common responses include:

Status Code

Meaning

200

Request processed successfully

201

Resource created successfully

202

Request accepted for processing

400

Invalid request or payload

401

Authentication failed

403

Access denied

404

Endpoint not found

429

Rate limit exceeded

500

Internal server error

Response codes are one of the most important troubleshooting tools.

Retries

Retries occur when a webhook request fails.

Many platforms automatically retry failed requests.

Common reasons for retries:

  • Temporary API outages
  • Network interruptions
  • Rate limits
  • Timeout errors
  • Internal server errors

Typical Retry Flow

Webhook Sent → Failure → Retry → Success

Retries help prevent data loss during temporary issues.

Common Retry Scenarios

Scenario

Typical Behavior

Temporary outage

Request retried automatically

Rate limit reached

Retry after waiting period

Timeout

Retry after delay

Network issue

Retry when connection restored

Invalid payload

Retry usually fails until corrected

Not all failures should be retried. Payload and authentication issues typically require configuration changes.

Common Webhook Issues

Issue

Resolution

Incorrect URL

Verify endpoint URL

Missing authentication

Add required headers

Invalid payload

Verify field mappings

Missing required fields

Populate required values

Rate limits

Reduce request volume

Timeouts

Review endpoint performance

Failed retries

Review logs and response codes
Best Practices

Recommended webhook practices:

  • Use authentication headers
  • Validate required fields
  • Monitor response codes
  • Review execution logs regularly
  • Test before publishing
  • Implement retry handling
  • Log failed requests
  • Use realistic test data

These practices improve reliability and simplify troubleshooting.

Final Validation

Before moving an integration into production:

  1. Confirm the webhook URL is correct.
  2. Confirm authentication is configured.
  3. Confirm required fields are present.
  4. Confirm payload formatting is valid.
  5. Verify successful response codes are returned.
  6. Test retry behavior if possible.
  7. Review logs for failures.
  8. Complete an end-to-end integration test.

Understanding inbound webhooks, outbound webhooks, authentication, payloads, and retries provides the foundation for building and troubleshooting reliable SalesAi integrations.