Webhooks

Receive real-time notifications for important events in your Setter AI integration

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:

1. Navigate to Settings > General
2. Enter your webhook endpoint URL in the “Webhook URL” field
3. 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": "[e-mail]",
  "contactWhatsappId": "1234567890",
  "contactPhoneNumber": "[phone]",
  "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": "[e-mail]",
  "contactWhatsappId": "1234567890",
  "contactPhoneNumber": "[phone]",
  "contactFullName": "John Doe",
  "contactFirstName": "John",
  "contactLastName": "Doe",
  "contactMetadata": {},
  "concatenatedConversation": "Full conversation history...",
  "botId": 123,
  "botIntegrationId": 456
}

Message Delivery Failed

Triggered when a WhatsApp message fails to deliver. Use this to implement fallback workflows — for example, triggering an SMS via Zapier when a WhatsApp message can’t be delivered.

Event Type: message_delivery_failed

Payload Example

{
  "type": "message_delivery_failed",
  "timestamp": "2025-12-04T10:30:00.000Z",
  "platformResourceId": "wamid.HBgLNDQ3...",
  "errorCode": 131026,
  "errorTitle": "Message undeliverable",
  "errorMessage": "Message failed to send because there were one or more errors related to your phone number.",
  "errorDetails": "The message could not be delivered.",
  "contactWhatsappId": "447911123456",
  "contactPhoneNumber": "[phone]",
  "contactFullName": "John Doe",
  "contactFirstName": "John",
  "contactLastName": "Doe",
  "contactEmail": "[e-mail]",
  "contactMetadata": {},
  "botIntegrationId": 456
}

Use case: SMS fallback via Zapier

If a WhatsApp message fails to deliver, you can use this webhook to trigger an SMS to the same contact:

1. Create a Zap with Webhook by Zapier as the trigger (Catch Hook)
2. Set your Zapier webhook URL as the Webhook URL in your Setter AI settings
3. Filter on type === "message_delivery_failed"
4. Use contactPhoneNumber to send an SMS via Twilio or another SMS provider

Payload Fields

Common Fields

Field	Type	Description
type	string	Event type identifier (appointment_booked, conversation_inactive, or message_delivery_failed)
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
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”])
concatenatedConversation	string | null	Complete conversation history

Message Delivery Failed Fields

Field	Type	Description
platformResourceId	string	The WhatsApp message ID (wamid) that failed to deliver
errorCode	number | null	WhatsApp error code (see Meta error codes)
errorTitle	string | null	Short error title
errorMessage	string | null	Detailed error message
errorDetails	string | null	Additional error context

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