Webhooks

Webhooks allow you to integrate external systems with Tether by sending contact data directly to your Tether instance. This guide covers the outreach webhook endpoint for creating new contacts programmatically.

POST/api/webhook/outreach

Create contact via webhook

This endpoint allows you to create a new contact in Tether by sending a webhook request. This is useful for integrating lead generation forms, CRM systems, or other external sources.

Required attributes

Name
configurationId
Type
string
Description
The configuration ID for the outreach campaign or source.
Name
phoneNumber
Type
string
Description
The phone number of the contact (with country code).
Name
firstName
Type
string
Description
The first name of the contact.
Name
lastName
Type
string
Description
The last name of the contact.

Optional attributes

Name
email
Type
string
Description
The email address of the contact.
Name
customData
Type
object
Description
Any additional dynamic properties to store with the contact.

Request

POST

/api/webhook/outreach

curl -X POST https://your-tether-instance.com/api/webhook/outreach \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "68d6d7de324658b8a1760d5e",
    "phoneNumber": "+12345671895",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }'

Success Response (200)

{
  "success": true,
  "message": "Lead received successfully and message sent.",
  "data": {
    "contactId": "507f1f77bcf86cd799439012",
    "conversationId": "507f1f77bcf86cd799439013",
    "applicationId": "507f1f77bcf86cd799439014"
  }
}

Dynamic contact properties

You can include additional contact properties beyond the required fields. Any extra fields in your request will be stored as custom data associated with the contact.

Example with custom properties

Include any additional fields that are relevant to your use case, such as company name, lead source, industry, or any other custom data.

Request with custom properties

curl -X POST https://your-tether-instance.com/api/webhook/outreach \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "68d6d7de324658b8a1760d5e",
    "phoneNumber": "+12345671895",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "company": "Acme Corp",
    "industry": "Technology",
    "leadSource": "Website Form",
    "budget": "$10,000"
  }'

Best practices

Always include the country code with phone numbers (e.g., +1 for US)
Validate phone number format before sending to avoid errors
Use meaningful configuration IDs to track different lead sources
Include as much contact information as possible to improve lead quality
Implement retry logic for failed webhook requests