Webhooks API

Manage webhook subscriptions to receive real-time event notifications. Leezy uses the RestHooks pattern for webhook management.

Subscribe to Webhooks

POST /api/v1/webhooks/subscribe

Required Scope: webhooks:manage

Request Body

{
  "target_url": "https://yourapp.com/webhooks/leezy",
  "event_types": ["lead.created", "lead.qualified"],
  "filters": {
    "chatbot_id": "chatbot_abc123"
  }
}

Field	Type	Required	Description
target_url	string	Yes	HTTPS URL to receive webhooks
event_types	array	Yes	Event types to subscribe to
filters	object	No	Optional filters (e.g., chatbot_id)

Example Request

curl -X POST "https://app.leezy.ai/api/v1/webhooks/subscribe" \
  -H "Authorization: Bearer lzy_at_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "event_types": ["lead.created"]
  }'

Response

{
  "data": {
    "id": "webhook_abc123",
    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "event_types": ["lead.created"],
    "filters": {},
    "status": "active",
    "secret": "lzy_ws_abc123xyz789...",
    "created_at": "2024-01-15T10:00:00Z"
  },
  "meta": {
    "api_version": "2024-01-01"
  }
}

Secret Shown Once

The secret is only returned when creating the subscription. Store it securely for webhook verification.

List Subscriptions

GET /api/v1/webhooks

Required Scope: webhooks:manage

Example Request

curl -X GET "https://app.leezy.ai/api/v1/webhooks" \
  -H "Authorization: Bearer lzy_at_your_token"

Response

{
  "data": [
    {
      "id": "webhook_abc123",
      "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
      "event_types": ["lead.created"],
      "filters": {},
      "status": "active",
      "failure_count": 0,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "api_version": "2024-01-01",
    "total": 1,
    "count": 1
  }
}

Delete Subscription

DELETE /api/v1/webhooks/:id

Required Scope: webhooks:manage

Example Request

curl -X DELETE "https://app.leezy.ai/api/v1/webhooks/webhook_abc123" \
  -H "Authorization: Bearer lzy_at_your_token"

Response

{
  "data": {
    "id": "webhook_abc123",
    "deleted": true
  },
  "meta": {
    "api_version": "2024-01-01"
  }
}

Available Event Types

Lead Events

Event	Description
lead.created	New lead captured
lead.updated	Lead information updated
lead.qualified	Lead marked as qualified
lead.converted	Lead converted to customer
lead.score_changed	Lead score changed

Conversation Events

Event	Description
conversation.started	New conversation started
conversation.ended	Conversation ended
conversation.message_received	New message received
conversation.sentiment_negative	Negative sentiment detected
conversation.sentiment_positive	Positive sentiment detected

Ticket Events

Event	Description
ticket.created	New support ticket created
ticket.updated	Ticket updated
ticket.resolved	Ticket resolved

Meeting Events

Event	Description
meeting.scheduled	Meeting scheduled
meeting.cancelled	Meeting cancelled
meeting.completed	Meeting completed
meeting.reminder	Meeting reminder sent

Other Events

Event	Description
message.feedback_negative	Negative feedback on message
message.feedback_positive	Positive feedback on message
agent.tool_failed	AI action failed
agent.tool_executed	AI action executed
usage.threshold_reached	Usage threshold reached

Subscription Status

Status	Description
active	Receiving webhooks normally
failed	Paused due to consecutive failures

Subscriptions are automatically paused after 5 consecutive delivery failures.

Error Responses

Status	Error	Description
400	invalid_request	Invalid URL or event types
401	unauthorized	Missing or invalid token
403	insufficient_scope	Token lacks webhooks:manage scope
404	not_found	Subscription not found

Next Steps

• Webhook Events - Event payload examples
• Webhook Security - Verify webhook signatures
• Webhooks Overview - Delivery and retry behavior