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": "campaign",
    "event_type_map": {
      "EMAIL_REPLY": true,
      "EMAIL_OPEN": 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
string
required
Scope of the webhook. Valid values:
  • user - User level (all campaigns)
  • client - Client level (all campaigns for a client)
  • campaign - 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. Set each event key to true to enable. Available events:
  • EMAIL_SENT - Email sent
  • FIRST_EMAIL_SENT - First email of sequence sent
  • EMAIL_OPEN - Email opened
  • EMAIL_LINK_CLICK - Link clicked
  • EMAIL_REPLY - Lead replied
  • EMAIL_BOUNCE - Email bounced
  • LEAD_UNSUBSCRIBED - Lead unsubscribed
  • LEAD_CATEGORY_UPDATED - Lead category changed
  • CAMPAIGN_STATUS_CHANGED - Campaign status changed
  • UNTRACKED_REPLIES - Untracked reply received
  • MANUAL_STEP_REACHED - Manual step reached in sequence
​
category_id_map
object
Map of category IDs to filter events by lead category
​
client_id
number
Client ID (required when association_type=2)
​
event_type
string
Specific event type to subscribe to
​
category_id
number
Specific lead category ID to filter events by
​
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": "campaign",
    "event_type_map": {
      "EMAIL_REPLY": true,
      "EMAIL_OPEN": true
    }
  }'

​
Webhook Payload

When an event occurs, SmartLead sends a POST request to your webhook_url. The payload structure varies by event type. Here’s an example for EMAIL_REPLY: 
{
  "event_type": "EMAIL_REPLY",
  "from_email": "sender@yourcompany.com",
  "subject": "Re: Quick question about Acme Corp",
  "to_email": "lead@example.com",
  "to_name": "John Doe",
  "time_replied": "2025-01-15T11:00:00Z",
  "reply_body": "<html>Thanks for reaching out...</html>",
  "preview_text": "Thanks for reaching out...",
  "campaign_name": "Q1 Outreach",
  "campaign_id": 123,
  "client_id": 456,
  "sequence_number": 1
}
See Webhook Events for all event payloads.

​
Association Types

Receives events from all campaigns owned by the user. Use when you want centralized notifications. If a User-level webhook exists, it takes priority over Client and Campaign-level webhooks.
Receives events from all campaigns for a specific client. Useful for agency/white-label setups. Requires client_id in the request body.
Receives events only from a specific campaign. Most common use case for per-campaign tracking. Requires email_campaign_id in the request body.

​
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"
}