Skip to main content
POST
/
api
/
v1
/
webhook
/
create
curl -X POST "https://server.smartlead.ai/api/v1/webhook/create?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reply Notifications",
    "webhook_url": "https://your-domain.com/webhook",
    "email_campaign_id": 123,
    "association_type": 3,
    "event_type_map": {
      "REPLIED": true,
      "OPENED": true
    }
  }'

{
  "ok": true,
  "id": 456,
  "webhook_url": "https://your-domain.com/webhook"
}
Webhooks allow you to receive real-time HTTP POST notifications when specific events occur in your campaigns. Configure webhooks at user, client, or campaign level.

​
Query Parameters

​
api_key
string
required
Your SmartLead API key

​
Request Body

​
webhook_url
string
required
The URL where webhook notifications will be sent via HTTP POST
​
association_type
number
required
Scope of the webhook. Valid values:
  • 1 - User level (all campaigns)
  • 2 - Client level (all campaigns for a client)
  • 3 - Campaign level (single campaign)
​
email_campaign_id
number
Campaign ID (required when association_type=3)
​
name
string
Webhook name for identification
​
event_type_map
object
Map of events to subscribe to. Common events:
  • SENT - Email sent
  • OPENED - Email opened
  • CLICKED - Link clicked
  • REPLIED - Lead replied
  • BOUNCED - Email bounced
  • UNSUBSCRIBED - Lead unsubscribed
​
category_id_map
object
Map of category IDs to filter events by lead category
​
client_id
number
Client ID (required when association_type=2)
​
webhook_type
string
Webhook type identifier
​
force_create
boolean
default:"false"
Force creation even if a similar webhook exists
curl -X POST "https://server.smartlead.ai/api/v1/webhook/create?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reply Notifications",
    "webhook_url": "https://your-domain.com/webhook",
    "email_campaign_id": 123,
    "association_type": 3,
    "event_type_map": {
      "REPLIED": true,
      "OPENED": true
    }
  }'

​
Webhook Payload

When an event occurs, SmartLead sends a POST request to your webhook_url with this structure: 
{
  "event_type": "REPLIED",
  "campaign_id": 123,
  "lead_email": "john@example.com",
  "lead_first_name": "John",
  "lead_last_name": "Doe",
  "email_account": "sender@yourdomain.com",
  "subject": "Re: Quick question",
  "message": "Thanks for reaching out...",
  "timestamp": "2025-11-26T10:30:00Z",
  "category_id": 5
}

​
Association Types

Receives events from all campaigns owned by the user. Use when you want centralized notifications.
Receives events from all campaigns for a specific client. Useful for agency/white-label setups.
Receives events only from a specific campaign. Most common use case for per-campaign tracking.

​
Response Codes

​
200
Success
Webhook created successfully
​
401
Unauthorized
Invalid or missing API key
​
422
Validation Error
Missing required fields or invalid association_type
​
500
Internal Server Error
Server error occurred
{
  "ok": true,
  "id": 456,
  "webhook_url": "https://your-domain.com/webhook"
}