Skip to main content

Create a webhook endpoint | Developer Documentation

Prepare a webhook endpoint for the ChatArchitect API

Use this checklist when building your own ChatArchitect API application. Prepare a public HTTPS callback receiver, confirm its request-handling contract, register it using the API quick start and test incoming messages and outgoing results. A ready-made connector can already manage its callback; confirm the existing connection before changing that setting.

The ChatArchitect API quick start documents callback registration and event examples. The webhook overview explains the two documented event kinds and matching results to attempts.

Prepare the receiver and its route

  • Choose a stable HTTPS route owned by your application, such as https://example.com/webhooks/chatarchitect. Replace this illustrative URL with your real receiver.
  • Check public DNS, TLS certificate validity and routing through your proxy to the intended application handler.
  • Check that callback requests reach the handler directly. An interactive login page or a redirect can change the result seen by the sender.
  • Arrange event validation, accepted-event recording and processing according to the agreed callback contract and your application's data policy.
  • Keep API credentials on the server. The App ID/Secret used for API registration has the role documented in the quick start.

Confirm the callback contract before production use

PartWhat to establish
Request handlingConfirm the callback request method and supported body format, and accept the documented JSON event shapes.
Sender verificationUse the verification mechanism supported for your ChatArchitect connection. Ask support for the current authentication or signature requirements before enabling business actions.
AcknowledgementConfirm the expected success response, response deadline and what constitutes successful receipt.
RedeliveryConfirm any retry behavior and design duplicate processing safely. Choose a record of event receipt and processing appropriate to your application.
Registration scopeConfirm which connection and existing callback receivers will be affected by changing the URL.

The current quick start describes an HTTPS receiver, event shapes and safe duplicate processing. It does not specify callback signature headers, acknowledgement deadlines or a retry schedule. Obtain those details for your integration; the schema check below validates data shape.

Validate and route the supported events

  1. Apply the sender-verification method agreed for the connection before trusting the event. Check that the body is valid JSON with the expected objects and fields.
  2. For root type = message-event, validate the status data and apply the delivery-status workflow for the matched attempt.
  3. For root type = message with payload.type = text, validate the sender and text fields, then route the incoming message to the intended conversation.
  4. Recognize a repeated event using a rule verified against your connection. Keep your processing safe if the same event is received again.
  5. Handle unknown or incomplete shapes according to the agreed contract and retain diagnostic information appropriate to your data policy.
  6. Separate receipt from business processing in your design. Send the agreed success response when you have accepted responsibility for the event; account for processing failures after that point.

Register the callback with ChatArchitect

Use Step 1 of the API quick start from your server. It documents POST /webhook at the ChatArchitect API with Basic Auth using the supplied App ID and Secret. Follow that guide's current request body and its phone-number formatting rules.

  1. Confirm the intended account/connection and the effect on any existing integration.
  2. Supply your real HTTPS callback URL using the documented registration workflow. Review the response for success or an error.
  3. Keep the registration result and time with time zone in your operational record, with credentials excluded.
  4. Check receipt and processing of the test events below before using the receiver with customers.

Verify the receiver in stages

StageEvidence to check
Local application testUse synthetic events based on the quick start's documented shapes. Check valid, incomplete, unknown and duplicate inputs according to your agreed contract.
Public routingCheck the real HTTPS route, TLS certificate and proxy-to-handler path from outside the server.
Incoming text testFollow the first-message guide with a permitted test account and verify receipt and routing of an incoming text.
Outgoing attempt testReply in the open service window, preserve the synchronous response and verify the later result against the same attempt.
Processing failure testCheck your recovery plan when accepted event processing fails, and verify duplicate handling independently of message sending.

If callbacks stop, check receipt at the proxy and handler, the registered URL, the connection, validation results and processing errors. Give support the receiver URL, connection, test time with time zone and redacted diagnostic sample.

Decide what diagnostic data your application needs and how it is retained. Follow the data-handling guide for your connected systems. The direct Meta callback setup is documented in Meta's endpoint reference; use ChatArchitect's supported contract for this connection.

No comments to display

Back to top