Skip to content

Enhanced Webhook Payload Documentation

Overview

ConnectGain webhooks now send detailed, enriched payloads that include complete contact, organization, and conversation objects instead of just IDs. This makes it easier for external systems to process webhook events without needing to make additional API calls.

Payload Structure

Base Payload Format

{
 "event": "message.received",
 "timestamp": "2025-01-15T12:34:56.789Z",
 "data": {
 // Event-specific data with enhanced objects
 }
}

Enhanced Data Fields

The data object now includes the following enhanced fields when applicable:

Contact Object

When a contact_id is present in the event data, the full contact object is included:

{
 "contact": {
 "id": "uuid",
 "organization_id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john.doe@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {},
 "opt_in_status": true,
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z",
 "company": {
 // Company details if associated
 "id": "uuid",
 "name": "Acme Corp",
 "domain": "acme.com",
 "website": "https://acme.com",
 "industry": "Technology",
 //... other company fields
 }
 }
}

Organization Object

When an organization_id is present, the full organization object is included:

{
 "organization": {
 "id": "uuid",
 "name": "My Organization",
 "slug": "my-org",
 "settings": {
 // Organization settings
 },
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z"
 }
}

Conversation Object

When a conversation_id is present, the full conversation object with related data is included:

{
 "conversation": {
 "id": "uuid",
 "organization_id": "uuid",
 "contact_id": "uuid",
 "channel_account_id": "uuid",
 "assignee_id": "uuid",
 "status": "OPEN",
 "sla_deadline": null,
 "last_message_at": "2025-01-15T12:00:00Z",
 "tags": [],
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z",
 "channel_account": {
 "id": "uuid",
 "type": "WHATSAPP_LITE",
 "name": "WhatsApp Business",
 "settings": {},
 "is_active": true
 },
 "assignee": {
 "id": "uuid",
 "first_name": "Agent",
 "last_name": "Smith",
 "email": "agent@example.com",
 "role": "AGENT"
 }
 }
}

Event Examples

message.received Event

{
 "event": "message.received",
 "timestamp": "2025-01-15T12:34:56.789Z",
 "data": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "content": "Hello, I need help with my order",
 "direction": "INBOUND",
 "status": "DELIVERED",
 "created_at": "2025-01-15T12:34:56.789Z",
 "channel_type": "WHATSAPP_LITE",
 "channel_name": "WhatsApp Business",
 "contact": {
 // Full contact object as shown above
 },
 "organization": {
 // Full organization object as shown above
 },
 "conversation": {
 // Full conversation object as shown above
 }
 }
}

message.sent Event

{
 "event": "message.sent",
 "timestamp": "2025-01-15T12:35:00.000Z",
 "data": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "content": "Thank you for reaching out. How can I help you today?",
 "direction": "OUTBOUND",
 "status": "SENT",
 "created_at": "2025-01-15T12:35:00.000Z",
 "contact": {
 // Full contact object
 },
 "organization": {
 // Full organization object
 },
 "conversation": {
 // Full conversation object
 }
 }
}

conversation.created Event

{
 "event": "conversation.created",
 "timestamp": "2025-01-15T12:30:00.000Z",
 "data": {
 "id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "created_at": "2025-01-15T12:30:00.000Z",
 "contact": {
 // Full contact object
 },
 "organization": {
 // Full organization object
 },
 "conversation": {
 // Full conversation object with channel_account details
 }
 }
}

Benefits

  1. No Additional API Calls: External systems receive all necessary data in a single webhook payload
  2. Complete Context: Full contact and organization details provide complete context for each event
  3. Related Data: Includes related entities like companies (for contacts) and channel accounts (for conversations)
  4. Consistent Structure: All webhook events follow the same enhanced payload structure

Migration Notes

  • The original fields (contact_id, organization_id, conversation_id) are still present for backward compatibility
  • The enhanced objects are added as additional fields (contact, organization, conversation)
  • If fetching enhanced data fails, the webhook still sends with the original IDs only
  • Enhanced data fetching is done asynchronously and doesn't block webhook delivery

Headers

Webhook requests include the following headers:

  • Content-Type: application/json
  • X-Webhook-Event: <event-type>
  • X-Webhook-Timestamp: <ISO-8601-timestamp>
  • X-Webhook-Signature: <HMAC-signature> (if webhook secret is configured)
  • Any custom headers configured in the webhook settings