Webhooks | Developer Documentation

Receive and understand WhatsApp webhooks from ChatArchitect

Use this guide for a custom service connected to the ChatArchitect API. Webhooks deliver incoming customer messages and later results of outgoing attempts to your application's callback receiver. The ChatArchitect API quick start documents the connection and event examples.

Choose the workflow for your connection

• Custom API application: prepare an HTTPS receiver using the endpoint checklist, then register the callback through the documented ChatArchitect API workflow.
• Ready-made CRM or help desk integration: check incoming chats and delivery results using that integration's instructions. Before changing a callback used by an existing integration, confirm the affected connection and receiver with ChatArchitect support. Use the receiver change checklist to prepare the scope and recovery plan.

ChatArchitect provides App ID and Secret for its API requests. Follow the API quick start for registration and credentials. Meta's direct API webhook subscriptions describe a separate developer connection; the customer workflow here uses ChatArchitect's documented events.

Identify the event before processing it

Check the root type first, then interpret the nested payload for that event kind. The current ChatArchitect guide documents these two cases:

Event	Documented fields	Application action
Outgoing result: root type = message-event	payload.type contains a status; payload.destination identifies the recipient and payload.id is the event's message reference. A failure can include payload.payload.reason.	Record the result against the relevant outgoing attempt using the correlation rule verified for your integration.
Incoming text: root type = message, payload.type = text	payload.source identifies the sender, payload.id is the message reference, and payload.payload.text contains the text.	Route the incoming text to the correct connection and customer conversation.

For incoming texts, use the text-event handling guide. For delivery states and incomplete results, use the delivery-status guide. A synchronous submitted response records acceptance into the sending queue; inspect the later outcome separately.

Keep enough information to match an attempt

• For each outgoing attempt, record your internal reference, connection, recipient, request time with time zone and returned messageId.
• For a callback, record its received time, root event type, available message reference, source or destination, and the status or text needed by your application.
• Verify how the callback reference maps to the original request in your supported integration. The quick start's sample messageId and callback payload.id differ; it does not establish a universal equality rule.
• Keep an unmatched event for investigation according to your data policy. Several attempts can involve the same phone number, so check the complete attempt context before applying a result.

Design processing to handle duplicate events safely, as the API guide recommends. Preserve the observed results and avoid treating arrival order as a documented status sequence. Decide how your application handles a delayed event or a repeated incoming message.

Check both directions with a small test

1. Confirm the receiver is reachable, registered for the intended connection and ready to process the documented event kinds. Work through the staged receiver test before using it for customer traffic.
2. Follow the first-message guide with a permitted test number. Send an incoming text and check the root message event and its routing into the correct conversation.
3. Reply in the open customer service window. Record the synchronous result and match any later message-event results to that specific attempt.
4. Compare receiver receipt, application processing and the message seen on the test phone. These observations establish different stages of the workflow.

For an incoming message with unavailable content, follow the unavailable-message guide. Confirm the contract for any additional event type before routing it as ordinary text or a delivery result.

If events are missing or routed incorrectly

Observed result	Next check
Receiver sees no callback	Check the registered URL and connection, public HTTPS reachability, proxy routing and the registration result. Give support the test time and affected connection.
Callback arrives but no chat or result appears	Inspect the root event kind, payload shape, parsing outcome and application routing. Check the supported sample in the API quick start.
Result appears against the wrong attempt	Review connection, recipient and message references together; verify the integration's correlation rule.
Repeated chat item or repeated action	Check how your handler recognizes and processes duplicate events without repeating the business action.
Failed attempt lacks a visible reason	Inspect the available failure details and application display. Preserve the result as received and use the delivery-status checklist.

For support, provide the connection, receiver URL, test time with time zone, available attempt references, receipt/processing result and exact error. Use a redacted event sample when needed. Handle your application's records according to the data-handling guide.

Route the event and review the customer identity

Use the checklists for message-event routing, usernames and user IDs and identity-change signals. Keep incoming messages separate from outgoing results; confirm the connection scope before matching a customer. A number or user-ID change is different from a potential cryptographic identity change, and technical acknowledgement does not establish customer trust.

When a workflow expects a catalog order

Native Meta product catalogs, product cards, shopping carts and receipt of catalog orders are not supported by ChatArchitect. The catalog availability guide explains the scope and ordinary product-information workflow. A customer's ordinary text can be handled with the incoming-text guide; receiving it does not establish a structured catalog-order event, stock update or payment.

When a customer shares a card, map point or reaction

Use the receiving checklists for shared contact cards, map locations and emoji reactions. Confirm support for the exact connection and the ChatArchitect field mapping before implementing these additional types. The quick start's text example does not define their callback format or automatic CRM changes.

When a message, customer identifier or PIN changes

Use the checklists for edited customer messages, customer identifier changes and business PIN notices. Confirm the event format and supported receiving behavior before automating CRM changes or alerts. The edit-event reference applies to coexistence; an identifier change may supply a user ID without a phone number. Check the business PIN in WhatsApp Manager through the confirmed client workflow.

When the WhatsApp Business app shares data

For a coexistence connection, check earlier chat history, address-book synchronization and business app sends separately. Confirm the available import/sync scope and callback mapping for the receiving tool. An imported old message or an echo of an existing business send should not trigger a fresh reply merely because it reached your receiver.

When template content or a customer's choice changes

Use the checklists for changed template content, template-button replies and marketing preference changes. Confirm the callback format, identity/original-message mapping and actions supported by the receiving tool. A component notice does not establish approval or a completed CRM refresh; receiving a choice does not establish that every dependent workflow or campaign list was updated.

When a template changes

Template management notices concern the template used by a workflow. Follow the checklists for status changes, quality changes and category changes. Check these in your account and with support as needed. The current API quick start does not define forwarding of these Meta management events to a ChatArchitect customer callback; confirm the additional contract before automating actions from them.

When account or number settings change

For a management notice affecting the connected account or number, use the checklists for account limit changes, display name review results and throughput changes. Confirm the current result in the applicable Meta tools or with support. The API quick start does not define forwarding of these management events to customer callbacks; confirm the additional contract before automating workflow changes.

When a workflow expects automatic advertising conversions

Automatic identification of leads or purchases from Click-to-WhatsApp conversations and reporting those events to Meta Conversions API are not supported by ChatArchitect. Use the Automatic Events availability guide and receiving checklist to distinguish this workflow from ordinary incoming messages and outgoing results. Confirm any separate advertising or analytics arrangement with its provider.

For the direct Meta developer interface, see Meta's webhook overview. It does not define the ChatArchitect callback contract.