C
Chatty

Complete Webhooks Reference

Chatty utilizes a bi-directional webhook architecture:

  1. Outbound Developer Webhooks: Chatty delivers real-time signed JSON events to your servers, CRM, and automation platforms (n8n, Zapier, Make) when customer interactions happen.
  2. Inbound Channel & Commerce Webhooks: Chatty ingests live messages and catalog updates from WhatsApp, Instagram, Telegram, Twilio SMS, Inbound Email, and WooCommerce.

Part 1: Outbound Developer Webhooks

Whenever a visitor interacts with your bot, Chatty evaluates active webhook subscriptions for that bot and dispatches events.

Subscribing to Events

Via Chatty Dashboard

  1. Go to Dashboard → Developer API → Webhooks.
  2. Click Add Webhook Subscription.
  3. Enter your HTTPS URL and select the event topics to listen to.
  4. Copy the generated HMAC Secret Key (whsec_...) immediately.

Via Developer REST API

Register Webhook
curl -X POST "https://api.chatty.personaliai.com/api/bots/{bot_id}/webhooks" \
  -H "Authorization: Bearer chatty_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourdomain.com/webhooks/chatty",
    "events": [
      "lead.created",
      "message.user",
      "message.assistant",
      "booking.confirmed",
      "handoff.requested",
      "session.ended"
    ]
  }'

Outbound Event Catalog & Payload Schemas

All outbound deliveries wrap event data in a standardized envelope:

Standard Envelope Schema
{
  "event": "string",
  "bot_id": "uuid",
  "session_id": "string",
  "timestamp": "ISO-8601 UTC timestamp",
  "data": { ... }
}

1. lead.created

Fired the instant a visitor provides contact information or when the flow extracts qualified lead data.

{
  "event": "lead.created",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:30:00.000Z",
  "data": {
    "lead_id": "ld_990142",
    "name": "Alex Morgan",
    "email": "alex.morgan@example.com",
    "phone": "+14155552671",
    "source_channel": "widget",
    "custom_fields": {
      "company_size": "50-200",
      "estimated_budget": 15000,
      "urgency": "immediate"
    }
  }
}

2. message.user

Fired when any customer message arrives (from widget, WhatsApp, Instagram, Telegram, SMS, or Email).

{
  "event": "message.user",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:30:15.000Z",
  "data": {
    "message_id": "msg_usr_123",
    "channel": "whatsapp",
    "content": "Do you offer international shipping to Canada?",
    "sender_identity": "+14155552671"
  }
}

3. message.assistant

Fired when the AI bot replies. Includes response latency in milliseconds and model execution metadata.

{
  "event": "message.assistant",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:30:17.200Z",
  "data": {
    "message_id": "msg_ast_456",
    "content": "Yes! We ship to Canada via DHL Express with 3-5 business day delivery.",
    "latency_ms": 780,
    "confidence_score": 0.96,
    "sources_cited": ["https://mystore.com/shipping-policy"]
  }
}

4. booking.confirmed

Fired when an appointment is successfully scheduled through Google Calendar or Microsoft Outlook integrations.

{
  "event": "booking.confirmed",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:31:00.000Z",
  "data": {
    "booking_id": "bk_77189bca",
    "attendee_name": "Elena Rostova",
    "attendee_email": "elena@example.com",
    "start_time": "2026-10-25T15:00:00Z",
    "end_time": "2026-10-25T15:30:00Z",
    "meeting_url": "https://meet.google.com/xyz-uvwx-rst",
    "calendar_provider": "google"
  }
}

5. handoff.requested

Fired when a visitor asks to speak with a human agent, or when sentiment/frustration analysis triggers human takeover.

{
  "event": "handoff.requested",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:32:10.000Z",
  "data": {
    "conversation_id": "conv_4412abef",
    "reason": "customer_requested_agent",
    "channel": "widget",
    "last_user_message": "Can I please speak to someone in technical billing?",
    "suggested_team": "Billing Support"
  }
}

6. csat.submitted

Fired when a customer submits a post-chat rating.

{
  "event": "csat.submitted",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T12:35:00.000Z",
  "data": {
    "rating": 5,
    "feedback_text": "Super fast and answered my questions immediately!",
    "agent_type": "ai"
  }
}

7. session.started & session.ended

  • session.started: Fired when the conversation is initialized.
  • session.ended: Automatically fired by Chatty's background cron scanner when a session has remained idle for 30 consecutive minutes.
{
  "event": "session.ended",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess_89a0b1c2",
  "timestamp": "2026-10-23T13:05:00.000Z",
  "data": {
    "idle_minutes": 30,
    "last_message_at": "2026-10-23T12:35:00.000Z",
    "total_messages": 8
  }
}

Cryptographic Signature Verification (X-Chatty-Signature)

Every outbound POST includes an X-Chatty-Signature header containing the HMAC-SHA256 hash of the raw, unparsed body bytes signed with your subscription secret.

Python (FastAPI / Flask / Django)
import hmac
import hashlib
 
def verify_chatty_signature(raw_body_bytes: bytes, signature_header: str, secret: str) -> bool:
    """Validate incoming X-Chatty-Signature header."""
    expected = hmac.new(secret.encode("utf-8"), raw_body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Do Not Pre-Parse Body

Always calculate the HMAC against the raw byte buffer. If your web framework parses the body to JSON first, re-stringifying it can modify key ordering or whitespace, resulting in validation failure.


Delivery Retries, Lease Locks & Dead-Letter Queue (DLQ)

Chatty guarantees durable delivery through Redis Streams and database-backed leases:

  1. Inline First Attempt: When an event triggers, Chatty publishes to the worker queue or attempts immediate HTTP POST.
  2. Timeout: Endpoints must return an HTTP 2xx response within 10 seconds.
  3. Lease Locking: When worker crons pick up retries, they acquire a randomized processing_token with a 10-minute lease cutoff. This prevents double-delivery across autoscaled instances.
  4. Exponential Backoff Schedule: Failed deliveries are rescheduled across 8 total attempts:
    AttemptDelay Before Next RetryCumulative Elapsed Time
    Attempt 1Immediate0s
    Attempt 21 second1s
    Attempt 35 seconds6s
    Attempt 430 seconds36s
    Attempt 55 minutes (300s)~5.5 min
    Attempt 630 minutes (1,800s)~35.5 min
    Attempt 72 hours (7,200s)~2.5 hours
    Attempt 88 hours (28,800s)~10.5 hours
  5. Dead-Letter Queue: If an endpoint fails after Attempt 8, delivery status transitions to failed and is stored in your bot's DLQ. Failed deliveries can be inspected and manually replayed from Dashboard → Webhook Logs.

Part 2: Inbound Channel Webhooks

Chatty provides production-ready webhook endpoints for receiving events from third-party networks:

1. WhatsApp Cloud API Webhook

  • Verification Endpoint: GET https://api.chatty.personaliai.com/webhook/whatsapp
    • Validates hub.mode=subscribe, hub.verify_token, and returns hub.challenge.
  • Receiver Endpoint: POST https://api.chatty.personaliai.com/webhook/whatsapp
    • Validates Meta's X-Hub-Signature-256.
    • Idempotency: Deduplicates incoming message IDs using Redis keys with a 1-hour TTL.
    • Automatically downloads voice notes, runs Whisper transcription, and handles images/PDFs.

2. Instagram Direct Webhook

  • Verification Endpoint: GET https://api.chatty.personaliai.com/webhook/instagram
  • Receiver Endpoint: POST https://api.chatty.personaliai.com/webhook/instagram
    • Subscribes to messages, messaging_postbacks, and message_deliveries.
    • Handles story mentions, media attachments, and quick replies.

3. Telegram Bot API Webhook

  • Receiver Endpoint: POST https://api.chatty.personaliai.com/webhook/telegram
    • Verifies X-Telegram-Bot-Api-Secret-Token.
    • Parses Telegram update objects (messages, photos, callback queries).

4. Twilio SMS / MMS Webhook

  • Receiver Endpoint: POST https://api.chatty.personaliai.com/webhook/twilio/sms
    • Verifies X-Twilio-Signature using your Twilio Auth Token.
    • Normalizes sender phone numbers into E.164 format and parses MMS image attachments.

5. Inbound Email Webhook

  • Receiver Endpoints:
    • POST https://api.chatty.personaliai.com/webhook/email/inbound
    • POST https://api.chatty.personaliai.com/webhook/resend-inbound
    • POST https://api.chatty.personaliai.com/api/webhooks/inbound-email
    • Supports Postmark, SendGrid, and Resend inbound parsing.
    • Automatically strips quoted reply history and runs AI retrieval to generate draft replies for your support agents.

Part 3: E-Commerce & Catalog Inbound Webhooks

WooCommerce Store Webhook

  • Endpoint: POST https://api.chatty.personaliai.com/api/integrations/woocommerce/webhook/{bot_id}
  • Security: Verifies X-WC-Webhook-Signature against your bot's WooCommerce secret.
  • Handled Topics:
    • product.created: Ingests and generates vector embeddings for new items.
    • product.updated: Updates prices, sale discounts, variant attributes, and stock status in real-time.
    • product.deleted: Purges removed items from RAG knowledge bases instantly.
    • order.created & order.updated: Caches fulfillment, shipment tracking, and delivery status for conversational order inquiries.

Catalog ERP/PIM Webhook

  • Endpoint: POST https://api.chatty.personaliai.com/api/integrations/catalog/webhook/{bot_id}
  • Synchronize product catalog data from SAP, Akeneo, Shopify, or internal databases using your custom external_id.
Catalog Sync Event
{
  "event": "product.updated",
  "external_id": "SKU-99401",
  "item": {
    "title": "Aero Carbon Road Bike",
    "price": 2899.00,
    "in_stock": true,
    "inventory_count": 18
  }
}

Part 4: Billing & Subscription Webhooks

  • Endpoint: POST https://api.chatty.personaliai.com/webhook/lemonsqueezy
  • Security: Verifies Lemon Squeezy's X-Signature.
  • Handled Events: subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, and order_created.
  • Automations: Automatically provisions plan quotas, updates team seats, and tracks affiliate referral commissions.

Best Practices & Security Checklist

Acknowledge Immediately

Return an HTTP 200 OK response within 10 seconds. Offload processing to a background job queue (Redis, Celery, SQS, BullMQ).

Always Validate Signatures

Reject any request that fails X-Chatty-Signature verification with an immediate 401 Unauthorized.

Ensure Idempotency

Network retries may cause duplicate delivery attempts. Use the event payload delivery_id or session_id + timestamp as an idempotency key.

SSRF Protection

Chatty validates outbound destination IPs and pins DNS connections to prevent internal network and loopback probing.