Chatbot API and Webhook Integration Architecture

Three directions, not one integration

Separate the three before choosing anything. Read: the bot fetches something live during a conversation — an order status, stock, an appointment slot. Act: the bot changes something in a system — books, creates, updates. Notify: something that happened in the conversation is pushed outward — a lead to the CRM, an alert to a team channel.

They have different risk profiles. A failed read is an inconvenience the bot can admit to. A failed or duplicated action is an incident. A failed notification is silent, which makes it the most dangerous of the three in practice, because nothing appears broken while leads quietly stop arriving.

They also have different owners. Reads usually need nothing more than an endpoint and a scoped credential. Actions need a policy decision about what may be changed. Notifications need someone to own the destination and notice when it goes quiet.

Live reads: what to fetch rather than index

The general rule is simple: if a fact changes faster than your update cycle, do not put it in the knowledge base. Fetch it.

• Order and delivery status, which changes hourly and is the single most requested live value in most businesses.
• Stock and availability, where an indexed answer is wrong within a day and wrong in the most annoying possible direction.
• Appointment and calendar availability, where offering a slot that is already taken is worse than offering nothing.
• Account-specific values — balance, plan, usage — which cannot be indexed at all without exposing one customer's data to another.
• Prices that vary by customer or contract, as opposed to published list prices which can be indexed safely.

Everything else is better indexed. A live call adds latency, a failure mode and a dependency, so it should buy you something that staleness would cost.

Designing a read that fails well

1. 1Set a timeout the customer can tolerateTwo or three seconds. A conversation that stalls for fifteen seconds while an API thinks has already lost the customer, whatever it eventually returns.
2. 2Define the message on timeout explicitly'I could not check that just now — I can have someone confirm it' is correct. Falling back to a plausible general answer is the single worst outcome, because the customer cannot tell the difference.
3. 3Never retry a read more than once inside a conversationRetries multiply latency. If the first attempt and one retry both fail, the answer is that you could not check.
4. 4Cache briefly where the value tolerates itStock can be seconds old. Balances usually cannot. Decide per value rather than globally.
5. 5Scope the credential to the readA token that can also write is a token that will eventually write.

Actions: what the bot may change

Actions are where integration becomes a governance question rather than a technical one. The technical part is easy; the part that causes incidents is scope.

• Enumerate actions individually. 'Manage bookings' is not an action; 'create a booking' and 'move a booking later within policy' are.
• Make every action idempotent, with a key derived from the conversation. Networks retry, customers double-tap, and a booking created twice is a support ticket you created yourself.
• Keep destructive actions behind a person. Cancellation, refund and deletion can be prepared by the bot and executed by a human at almost no cost to experience.
• Bound every parameter — how far ahead, how many times, within which hours, up to what value.
• Return a confirmation the customer can act on, including a reference. An action the customer cannot verify will be attempted again.
• Log the action with the conversation attached, so a disputed change can be investigated rather than argued about.

Outbound events: the direction that fails silently

This is the direction most likely to break unnoticed, because nothing on the customer's side changes when it does. A lead that never reached the CRM looks exactly like a week with fewer leads.

• Make delivery observable. Someone should be able to answer 'did the last hour's leads arrive?' without opening a database.
• Retry with backoff, and cap the retries. An endpoint that is down for an hour should not receive four thousand duplicate deliveries when it returns.
• Include an event identifier so the receiver can deduplicate. At-least-once delivery is the normal guarantee, and receivers have to be built for it.
• Alert on absence, not only on error. The failure mode you will actually meet is silence, and a threshold like 'no leads in four hours during business hours' catches it.
• Keep the payload small and stable. A webhook that ships the entire conversation body couples two systems together in a way that breaks on the first schema change.
• Version the payload. You will change it, and the receiver will not deploy on your schedule.

Security boundaries

Each direction needs a different boundary, and the ones below are the failures that actually occur rather than a general checklist.

• Allow-list outbound destinations. A system that will call an address supplied at runtime can be pointed at your internal network.
• Never let conversation content determine a destination or a parameter without validation. The customer's message is untrusted input at every boundary.
• Treat API responses as data, not as instruction. A record containing text that reads like a command to the model is a real attack, not a theoretical one.
• Scope every credential to one purpose, and rotate them on a schedule somebody owns.
• Rate-limit per conversation and per customer, so one conversation cannot become a load generator against your own systems.
• Do not return more than the answer needs. An endpoint that returns the full customer record because it was convenient has widened the blast radius of every other mistake.

How integration works in Vexvon

On the messaging side, a company registers its own APIs as tools the AI engine may call during a conversation — the live-read direction described above — with protection against requests being aimed at internal or otherwise unsafe destinations. That is the mechanism behind answering 'where is order 1234?' from the system that actually knows.

On the voice side the tool model is explicit and falls into three kinds: static values, built-in actions such as transferring a call, ending a call or searching the knowledge base, and webhooks to your own endpoints. Scenarios define which tools a given call may use along with its direction, language, voice and the fields to extract — so the action scope is configured per scenario rather than granted globally.

The outbound direction runs through triggers: a lead can be delivered as a Telegram notification to the sales group with a Start button, pushed to Bitrix24, or written to the built-in CRM, with every action recorded in an activity log covering ten types. Because delivery is a configured destination rather than an implicit side effect, the 'did it arrive' question has a place to be answered.

Cost and behaviour are observable across all of it: AI usage is logged across seventeen distinct purposes with model, channel and latency, and per call the tokens, success rate and dollar cost are recorded — which is what makes an integration problem diagnosable rather than anecdotal.

Frequently asked questions

1. 1What should a chatbot fetch live rather than index?Anything that changes faster than your update cycle: order status, stock, appointment availability, account-specific values and contract pricing. Published list prices and stable policies are better indexed.
2. 2What timeout should a live lookup have?Two or three seconds, with an explicit message when it expires. A conversation stalled for fifteen seconds has already lost the customer regardless of what eventually returns.
3. 3Should the bot be allowed to take actions?Yes for bounded, idempotent and reversible ones — creating a booking, creating a lead, updating a preference. Cancellation, refund and deletion should be prepared by the bot and executed by a person.
4. 4Why does idempotency matter here?Networks retry and customers double-tap. Without a key derived from the conversation, a single request becomes two bookings, and you have generated your own support ticket.
5. 5What is the most common integration failure?Outbound events failing silently. Nothing appears broken on the customer's side, so a CRM that stopped receiving leads looks identical to a quiet week. Alert on absence, not only on error.
6. 6What are the essential security boundaries?Allow-listed destinations, no destination or parameter chosen by conversation content without validation, API responses treated as data rather than instruction, narrowly scoped credentials, and per-conversation rate limits.

Start by listing the three directions

Before evaluating any integration capability, write three short lists: what the bot needs to read live, what it may change, and what must be pushed outward when a conversation ends. Most teams find the third list is the one nobody had thought about, and it is the one whose failure is silent.