Webhook Event Types

CloudContactAI sends webhook notifications to your configured endpoint when specific events occur in your account. All events follow a consistent structure with an eventType and data object containing event information.

Webhook Configuration

Configure your webhook URL in the CloudContactAI dashboard under Client Settings > Webhooks. All event types will be sent to the same endpoint using the HTTP method you specify (POST or PUT).

Event Types

message.sent

Description: Triggered when a message is successfully sent from CloudContactAI to a contact.

When it's sent:

• Message has been sent to the Contact.
• Occurs for both individual messages and campaign messages
• Includes pricing and segmentation information

JSON Example:

{
  "eventType": "message.sent",
  "data": {
    "SmsSid": 12345,
    "MessageStatus": "DELIVERED",
    "To": "+1234567890",
    "Message": "Hello! Your order #12345 has been shipped.",
    "CustomData": "order_id:12345,customer_type:premium",
    "ClientExternalId": "customer_abc123",
    "CampaignId": 67890,
    "CampaignTitle": "Order Notifications",
    "Segments": 2,
    "TotalPrice": 0.02
  }
}

message.incoming

Description: Triggered when a recipient replies to one of your messages or sends a message to your CloudContactAI phone number.

When it's sent:

• Message received from external phone number
• Processed through CloudContactAI's incoming message system
• Contact is not blocked from sending messages

JSON Example:

{
  "eventType": "message.incoming",
  "data": {
    "SmsSid": 0,
    "MessageStatus": "RECEIVED",
    "To": "+0987654321",
    "Message": "Yes, I'm interested in learning more!",
    "CustomData": "",
    "ClientExternalId": "customer_abc123",
    "CampaignId": 67890,
    "CampaignTitle": "Lead Generation Campaign",
    "From": "+1234567890",
    "To": "+0987654321"
  }
}

message.excluded

Description: Triggered when a message is excluded from being sent during campaign creation due to filtering rules.

When it's sent:

• Contact matches exclusion criteria (duplicate phone, invalid format, etc.)
• The exclusion process occurs prior to the processing of the campaign before messages are sent.
• Helps track why certain contacts didn't receive messages

JSON Example:

{
  "eventType": "message.excluded",
  "data": {
    "SmsSid": 0,
    "MessageStatus": "EXCLUDED",
    "To": "+1234567890",
    "Message": "Hi {{name}}, check out our new products!",
    "CustomData": "lead_source:website,segment:new_users",
    "ClientExternalId": "customer_xyz789",
    "CampaignId": 67890,
    "CampaignTitle": "Product Launch Campaign",
    "ExcludedReason": "Duplicate phone number in campaign"
  }
}

Common Exclusion Reasons:

• "Duplicate phone number in campaign"
• "Invalid phone number format"
• "Contact opted out"
• "Phone number blacklisted"

message.error.carrier

Description: Triggered when a message fails to be delivered due to carrier specific errors.

When it's sent:

• Carrier returns an error status for the message
• Network or carrier-specific delivery failures
• Invalid destination numbers or carrier restrictions

JSON Example:

{
  "eventType": "message.error.carrier",
  "data": {
    "SmsSid": 12345,
    "MessageStatus": "FAILED",
    "To": "+1234567890",
    "Message": "Your verification code is: 123456",
    "CustomData": "verification_attempt:1",
    "ClientExternalId": "user_def456",
    "CampaignId": 0,
    "CampaignTitle": "",
    "ErrorCode": "30008",
    "ErrorMessage": "Unknown destination handset",
    "ErrorType": "carrier"
  }
}

Common Carrier Error Codes:

• 30008: Unknown destination handset
• 30007: Message delivery failed
• 21211: Invalid 'To' phone number
• 21614: 'To' number is not a valid mobile number

message.error.cloudcontact

Description: Triggered when a message fails due to internal CloudContactAI system errors.

When it's sent:

• Internal processing errors (CCAI- prefixed error codes)
• System configuration issues
• Account or subscription related problems

JSON Example:

{
  "eventType": "message.error.cloudcontact",
  "data": {
    "SmsSid": 12345,
    "MessageStatus": "FAILED",
    "To": "+1234567890",
    "Message": "Welcome to our service!",
    "CustomData": "signup_source:landing_page",
    "ClientExternalId": "new_user_ghi789",
    "CampaignId": 67890,
    "CampaignTitle": "Welcome Series",
    "ErrorCode": "CCAI-001",
    "ErrorMessage": "Insufficient account balance",
    "ErrorType": "cloudcontact"
  }
}

Common CloudContactAI Error Codes:

• CCAI-001: Insufficient account balance
• CCAI-002: Account suspended
• CCAI-003: Message quota exceeded
• CCAI-004: Invalid campaign configuration

contact.unsubscribed

Description: Triggered when an incoming message is received with some of this texts (cancel, end, quit, stop, stopall, unsubscribe) and the contact will be flagged as "do not text".

When it's sent:

• Message received from external phone number with text cancel, stop, etc.
• Contact is flagged as do not text manually
• AI prompts checking the incoming message and decide to flag as do not text

JSON Example:

{
    "eventType": "contact.unsubscribed",
    "data": {
        "id": 0,
        "MessageStatus": "DO_NOT_TEXT",
        "To": "+0987654321",
        "Message": "STOP",
        "CustomData": "",
        "ClientExternalId": "customer_abc123",
        "CampaignId": 67890,
        "CampaignTitle": "Lead Generation Campaign",
        "UnsubscribedAt": "2025-09-25T11:08:14.368388Z",
        "ContactData": {
            "firstName": "Jon",
            "lastName": "Doe",
            "email": null,
            "phone": "+0997654321"
        }
    }
}