Overview
Setter AI sends webhook notifications to your server when important events occur, allowing you to build real-time integrations and automate workflows.
Setting Your Webhook URL
Configure your webhook URL in the Setter AI dashboard:
- Navigate to Settings > General
- Enter your webhook endpoint URL in the “Webhook URL” field
- Save your settings
Alternatively, you can configure it via API:
PUT /api/v1/organizations/current/settings
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"webhookUrl": "https://api.example.com/webhook"
}
Your webhook endpoint must accept POST requests with Content-Type: application/json.
Webhook Events
Appointment Booked
Triggered when a contact successfully books an appointment through any connected calendar integration.
Event Type: appointment_booked
Payload Example
{
"type": "appointment_booked",
"timestamp": "2025-12-04T10:30:00.000Z",
"startTime": "2025-12-05T14:00:00.000Z",
"startTimeInTz": "2025-12-05T09:00:00-05:00",
"endTime": "2025-12-05T15:00:00.000Z",
"timeZone": "America/New_York",
"contactEmail": "user@example.com",
"contactWhatsappId": "1234567890",
"contactPhoneNumber": "+1234567890",
"contactFullName": "John Doe",
"contactFirstName": "John",
"contactLastName": "Doe",
"contactMetadata": {},
"concatenatedConversation": "Full conversation history...",
"botId": 123,
"botIntegrationId": 456
}
Conversation Inactive
Triggered 23 hours after the last user message in a conversation.
Event Type: conversation_inactive
Payload Example
{
"type": "conversation_inactive",
"timestamp": "2025-12-04T10:30:00.000Z",
"lastUserMessageSentAt": "2025-12-03T11:30:00.000Z",
"inactiveForDuration": "PT23H",
"conversationStatus": ["replied"],
"contactEmail": "user@example.com",
"contactWhatsappId": "1234567890",
"contactPhoneNumber": "+1234567890",
"contactFullName": "John Doe",
"contactFirstName": "John",
"contactLastName": "Doe",
"contactMetadata": {},
"concatenatedConversation": "Full conversation history...",
"botId": 123,
"botIntegrationId": 456
}
Payload Fields
Common Fields
| Field | Type | Description |
|---|
type | string | Event type identifier (appointment_booked or conversation_inactive) |
timestamp | ISO 8601 | When the event occurred (UTC) |
contactEmail | string | null | Contact’s email address |
contactWhatsappId | string | null | WhatsApp user ID |
contactPhoneNumber | string | null | Contact’s phone number |
contactFullName | string | null | Contact’s full name |
contactFirstName | string | null | Contact’s first name |
contactLastName | string | null | Contact’s last name |
contactMetadata | object | null | Custom metadata associated with the contact |
concatenatedConversation | string | null | Complete conversation history |
botId | number | null | Bot identifier |
botIntegrationId | number | Integration identifier |
Appointment-Specific Fields
| Field | Type | Description |
|---|
startTime | ISO 8601 | Appointment start time (UTC) |
startTimeInTz | ISO 8601 | Appointment start time in the invitee’s timezone |
endTime | ISO 8601 | Appointment end time (UTC) |
timeZone | string | IANA timezone identifier (e.g., “America/New_York”) |
Conversation Inactive Fields
| Field | Type | Description |
|---|
lastUserMessageSentAt | ISO 8601 | Timestamp of the last user message |
inactiveForDuration | ISO 8601 Duration | Duration of inactivity (e.g., “PT23H” = 23 hours) |
conversationStatus | string[] | Array of conversation status tags (e.g., [“appointment_booked”, “replied”]) |
Best Practices
Implement Idempotency: Your webhook endpoint should handle duplicate events gracefully. Use the timestamp and event-specific fields to deduplicate requests.
- Respond Quickly: Return a 2xx status code within 5 seconds to acknowledge receipt
- Process Asynchronously: Queue webhook processing for longer operations
- Secure Your Endpoint: Use HTTPS and validate webhook signatures (if implemented)
- Handle Failures: Implement retry logic with exponential backoff on your side
