v1.0 • Lead Management
Complete API documentation for managing webhooks programmatically.
All webhook management endpoints accept your workspace API key —Authorization: Bearer sk-workspace_… — the same key used by the chat and leads endpoints. The chatbot must belong to the key's workspace. (Requests from the dashboard use your login session instead.)
https://pollybot.app/api/v1/chatbots/{chatbotId}/webhooksGET /api/v1/chatbots/{chatbotId}/webhooksRetrieve all webhooks for a specific chatbot with delivery statistics.
{
"webhooks": [
{
"id": "webhook_123",
"name": "Lead Notifications",
"url": "https://yourapp.com/webhook",
"eventTypes": ["LEAD_CREATED"],
"isActive": true,
"maxRetries": 3,
"retryDelay": 1000,
"successCount": 25,
"failureCount": 2,
"lastTriggeredAt": "2025-10-10T14:30:00.000Z",
"lastSuccessAt": "2025-10-10T14:30:00.000Z",
"lastFailureAt": "2025-10-10T12:15:00.000Z",
"createdAt": "2025-10-01T10:00:00.000Z",
"updatedAt": "2025-10-10T14:30:00.000Z"
}
],
"total": 1
}POST /api/v1/chatbots/{chatbotId}/webhooks{
"name": "Lead Notifications",
"url": "https://yourapp.com/webhook",
"eventTypes": ["LEAD_CREATED"],
"maxRetries": 3, // Optional: 0-10, default 3
"retryDelay": 1000 // Optional: 100-60000ms, default 1000
}{
"message": "Webhook created successfully",
"webhook": {
"id": "webhook_123",
"name": "Lead Notifications",
"url": "https://yourapp.com/webhook",
"secret": "whsec_1234567890abcdef...", // Only returned on creation!
"eventTypes": ["LEAD_CREATED"],
"isActive": true,
"maxRetries": 3,
"retryDelay": 1000,
"successCount": 0,
"failureCount": 0,
"createdAt": "2025-10-10T14:30:00.000Z",
"updatedAt": "2025-10-10T14:30:00.000Z"
},
"security": {
"note": "Store the secret securely. It will not be shown again.",
"headerName": "X-Webhook-Signature",
"format": "sha256=<hmac_signature>"
}
}The webhook secret is only returned once during creation. Store it securely - you'll need it to verify webhook signatures.
GET /api/v1/chatbots/{chatbotId}/webhooks/{id}Retrieve a specific webhook with detailed delivery statistics and recent delivery history.
{
"webhook": {
"id": "webhook_123",
"name": "Lead Notifications",
"url": "https://yourapp.com/webhook",
"eventTypes": ["LEAD_CREATED"],
"isActive": true,
"maxRetries": 3,
"retryDelay": 1000,
"deliveries": [
{
"id": "delivery_456",
"attempt": 1,
"status": "SUCCESS",
"httpStatus": 200,
"responseTime": 245,
"deliveredAt": "2025-10-10T14:30:00.000Z",
"createdAt": "2025-10-10T14:30:00.000Z"
},
{
"id": "delivery_457",
"attempt": 2,
"status": "FAILED",
"httpStatus": 500,
"errorMessage": "Internal Server Error",
"createdAt": "2025-10-10T14:25:00.000Z"
}
],
"createdAt": "2025-10-01T10:00:00.000Z",
"updatedAt": "2025-10-10T14:30:00.000Z"
}
}PUT /api/v1/chatbots/{chatbotId}/webhooks/{id}{
"name": "Updated Webhook Name",
"url": "https://new-endpoint.com/webhook",
"eventTypes": ["LEAD_CREATED"],
"isActive": false,
"maxRetries": 5,
"retryDelay": 2000
}{
"message": "Webhook updated successfully",
"webhook": {
"id": "webhook_123",
"name": "Updated Webhook Name",
"url": "https://new-endpoint.com/webhook",
"eventTypes": ["LEAD_CREATED"],
"isActive": false,
"maxRetries": 5,
"retryDelay": 2000,
"createdAt": "2025-10-01T10:00:00.000Z",
"updatedAt": "2025-10-10T15:00:00.000Z"
}
}DELETE /api/v1/chatbots/{chatbotId}/webhooks/{id}Permanently delete a webhook and all its delivery history. This action cannot be undone.
{
"message": "Webhook deleted successfully"
}{ "error": "Unauthorized" }{ "error": "Webhook not found or access denied" }{
"error": "Validation error",
"details": [
{
"code": "invalid_url",
"message": "Invalid URL format",
"path": ["url"]
}
]
}