Conversation-Ended Webhooks: Reliable WhatsApp and Web Chat Automation

A conversation-ended webhook turns a completed WhatsApp or web chat into a processable business event. Instead of copying transcripts manually, an enterprise can send structured outcomes directly to a CRM, help desk, data warehouse, or automation. The critical question is not merely whether a webhook is sent. In production, the pipeline must remain reliable through timeouts, duplicate events, media attachments, and conversations that span multiple days.

After a chat conversation ends, Famulor can deliver the complete transcript, extracted variables, input variables, customer and sender data, and timestamps. WhatsApp events may also include images, audio, video, and documents as attachments. This blueprint shows how to turn that payload into an enterprise-grade integration.

What the conversation-ended webhook covers

The webhook is designed for asynchronous work after a conversation. Typical outcomes include creating a lead, updating a ticket, archiving a summary, or starting a follow-up workflow. It is different from a Mid-call Action: Mid-call Actions access systems during a live interaction; the conversation-ended webhook hands off the result after a WhatsApp or web widget conversation has ended.

The reliable target architecture: acknowledge fast, process later

A webhook endpoint should do as little synchronous work as possible. It receives the event, validates the basic shape, stores the unchanged payload, and places a job on a queue. CRM updates, media analysis, notifications, and larger transformations happen afterwards. This lets the endpoint return a 2xx response quickly and avoids unnecessary redelivery.

1. Ingest the event: Limit payload size, parse JSON, and validate required fields such as conversation_id and status.
2. Store it unchanged: Save the raw payload with receipt time and an internal delivery state. This creates an auditable source for future replays.
3. Deduplicate: For conversation-ended events, conversation_id is a useful business key. The database should not record the same completion twice as a new case.
4. Process asynchronously: A worker performs field mapping, CRM upserts, ticket creation, analytics, and notifications.
5. Record the outcome: Capture the target system, API result, attempt count, and error class. This turns “webhook sent” into a measurable process.

Retries are a safety net, not processing logic

If the configured endpoint fails or does not return a 2xx status, Famulor retries delivery after 30, 60, and 120 seconds. After three failed retries, the delivery is marked as failed. This schedule absorbs brief network and platform incidents, but it does not replace a queue or idempotency in the destination system.

The core rule is simple: redelivery must not trigger the same business action twice. A CRM upsert is safer than a blind create operation. For downstream actions, a dedicated idempotency table can store conversation_id + action_name. The worker can then determine whether it has already created a ticket, sent an email, or updated a deal.

Replay and audit trails for day-to-day operations

Famulor records a webhook delivery result, including its status and response. Teams can resend the webhook for an individual conversation, while list views support bulk re-evaluation and redelivery. This becomes valuable when a CRM was temporarily unavailable or a field mapping has been corrected.

A controlled replay process needs three rules:

• Replay is idempotent: The destination updates the same record instead of creating duplicates.
• Original and transformation stay separate: The raw payload is immutable; transformed data receives a version.
• Every attempt is visible: Record the time, initiator, transformation version, and result.

The complete field reference and retry behavior are documented in the Famulor conversation-ended webhook documentation.

Process media attachments safely

WhatsApp conversations may include images, audio, video, and documents. The webhook exposes an attachments array with a type, URL, and filename. Do not treat these URLs as trusted internal files. A sound media pipeline downloads content server-side, enforces size and type limits, scans files, and retains them only for the stated business purpose.

• Validate the actual content type, not only the filename extension.
• Set download and processing time limits.
• Separate personal data by role and tenant.
• Log retention, deletion, and access.
• Move analysis failures to a dead-letter queue without losing the original event.

For outbound WhatsApp messages, the read receipts webhook adds statuses such as sent, delivered, read, and failed. This webhook is signed with HMAC-SHA256. Verify the signature over the untouched request body and deduplicate status updates by message ID and status.

Turn technical events into meaningful operating metrics

A webhook project is not production-ready until its state is visible. A useful operations dashboard can start with a short metric set:

• Share of events accepted on the first attempt
• End-to-end time from conversation end to a successful destination update
• Count and age of pending or failed jobs
• Replay rate and most common error class
• Share of events with attachments and media-processing failure rate
• Rate of missing required fields in the CRM mapping

These metrics reveal more than infrastructure problems. A sudden rise in missing qualification fields may indicate that a prompt or conversation flow has changed. Webhook observability therefore connects platform operations with Conversational AI quality.

Implementation checklist

1. Enable the conversation-ended webhook for the assistant and configure an HTTPS endpoint.
2. Define the target schema for the CRM, help desk, or data warehouse.
3. Create a raw event store and a unique idempotency key.
4. Define queue, worker, retry, and dead-letter behavior.
5. Secure the media path with content-type, size, malware, and retention rules.
6. Test WhatsApp, web widget, multi-day chats, human takeover, and attachment scenarios.
7. Simulate a failed delivery and prove that replay creates no duplicate.
8. Document alerting and ownership for stuck events.

Teams without an automation architecture can start with the Famulor Automation Platform or integrate through the API and their own queue. For WhatsApp-specific workflows, Famulor WhatsApp AI provides the channel layer.

FAQ

How is a conversation-ended webhook different from a post-call webhook?

The conversation-ended webhook covers chat conversations on WhatsApp and the web widget. Phone calls use the post-call webhook. Both can start downstream workflows, but their payloads and channel metadata differ.

Can the same event arrive more than once?

Yes. Redelivery is a normal possibility with webhooks, especially after a timeout or non-2xx response. The receiver should therefore make every processing step idempotent.

Which ID should be used for deduplication?

For the completion of a chat conversation, conversation_id is the central business key. For individual downstream actions, combine the conversation ID with an action name.

Should the HTTP handler update the CRM directly?

That can work for a small test, but a queue is more reliable in production. The handler can acknowledge quickly while a worker updates external systems with independent error handling.

What is the best way to start?

Begin with one destination and one clear outcome, such as “upsert a qualified lead in the CRM.” Add media analysis, notifications, and additional automations only after that path is observable and replay-safe.