Milestone Triggers API

Create and manage milestone triggers that fire when leads reach specific score thresholds or perform key actions. Milestone triggers can send webhook notifications, email alerts, or Slack/Teams messages when conditions are met.

GET /triggers

List all milestone triggers for the active Organizational Unit.

Request

No query parameters required.

Response

200 OK

{
  "triggers": [
    {
      "id": "trigger-123",
      "name": "High Score Alert",
      "event_type": "page_view",
      "score_threshold": 75,
      "webhook_url": "https://hooks.example.com/leadvibe",
      "emails": ["sales@example.com"],
      "active": true,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Example

curl -X GET "https://api.leadvibe.com/triggers" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

POST /triggers

Create a new milestone trigger.

Request

Parameter	Type	Required	Description
name	string	Yes	Trigger name for identification
event_type	string	No	Event type to monitor (e.g., page_view, form_submit). When omitted, trigger fires on any event that crosses the threshold.
score_threshold	integer	Yes	Lead score required to fire the trigger
webhook_url	string	No	URL to receive the webhook payload when the trigger fires
emails	array	No	Email addresses to notify when the trigger fires
email_subject	string	No	Custom subject line for email notifications
email_preheader	string	No	Preheader text for email notifications
email_message	string	No	Custom message body included before lead metadata in the email

Request Body

{
  "name": "Hot Lead Alert",
  "event_type": "demo_request",
  "score_threshold": 75,
  "webhook_url": "https://hooks.example.com/leadvibe",
  "emails": ["sales@example.com"],
  "email_subject": "Hot Lead Alert",
  "email_message": "A lead just crossed the 75-point threshold!"
}

Response

201 Created

{
  "id": "trigger-456",
  "name": "Hot Lead Alert",
  "event_type": "demo_request",
  "score_threshold": 75,
  "webhook_url": "https://hooks.example.com/leadvibe",
  "emails": ["sales@example.com"],
  "active": true,
  "created_at": "2025-01-15T10:30:00Z"
}

Example

curl -X POST "https://api.leadvibe.com/triggers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hot Lead Alert",
    "event_type": "demo_request",
    "score_threshold": 75,
    "webhook_url": "https://hooks.example.com/leadvibe",
    "emails": ["sales@example.com"]
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	Missing required fields or invalid values
401	Unauthorized	Check authentication token

---

Webhook Payload

When a milestone trigger fires, the webhook receiver gets a JSON payload with the event details, the lead's current score, and metadata about the trigger that fired.

{
  "trigger": {
    "id": "trigger-456",
    "name": "Hot Lead Alert",
    "type": "milestone"
  },
  "event": {
    "id": "evt-789",
    "lead_id": "ld_123",
    "event_type": "demo_request",
    "metadata": {
      "source": "website",
      "page": "/pricing"
    },
    "created_at": "2025-01-15T10:35:00Z"
  },
  "score": 82
}

Payload Fields

Field	Type	Description
trigger	object	Metadata about the trigger that fired
trigger.id	string	Unique trigger identifier
trigger.name	string	Trigger name
trigger.type	string	Always "milestone" for milestone triggers
event	object	The engagement event that matched the trigger
score	integer	Lead's score at the time the trigger fired

---

Notes

• Milestone triggers are OU-scoped like all lead data
• A trigger fires once per lead per threshold crossing (not on every qualifying event)
• Provide webhook_url for system-to-system integrations or emails for human notifications (or both)
• Customize email notifications with email_subject, email_preheader, and email_message
• Use the simulate endpoint to test triggers before activating them

Related Endpoints

• Milestone Trigger by ID - Update, delete, and simulate triggers
• Sequence Triggers - Multi-event triggers
• Milestone Events - View triggered events history