Update your backend when an assistant finishes
Section: DOC-IN-webhooks#react-to-platform-events-in-your-backend.
Your application has asked an assistant to draft an order summary. The customer can leave the screen while it works; your backend still needs to record whether the run finished and make its result available. Use a webhook to receive that update without keeping the customer's browser connected.
Travila delivers the event to your receiver. Your application owns the order record and decides what to do with the completed result.
Build the completion workflow
Section: DOC-IN-webhooks#start-here.
- Create a backend receiver that verifies and durably accepts incoming events.
- Register its URL and subscribe to
llm.generation_completed. - Start an ordinary assistant run and save its run ID with the order in your application.
- On a matching completion event, inspect the run's outcome before marking the order summary ready.
- Confirm both the delivery and your application's update. A successful delivery alone does not prove that your worker completed its work.
Follow the receiver setup recipe for these steps. If an update is missing, use the recovery recipe.
Prepare the receiving service
Section: DOC-IN-webhooks#how-it-works.
You need an HTTPS URL your backend controls, a backend API key, and an existing conversation that can produce a run. Webhook configuration belongs to the tenant and uses a secret API key without X-On-Behalf-Of. Keep that key and the endpoint's signing secret out of browser code.
Configure your receiver before starting customer work. An endpoint receives nothing until it has a subscription, and events produced before that subscription are not a historical backfill.
Choose the event for your application result
Section: DOC-IN-webhooks#event-types.
For the order-summary workflow, select llm.generation_completed. Completion includes unsuccessful outcomes; read the event's status before showing the summary as ready.
| A different application need | Event to evaluate |
|---|---|
| Add each new conversation message to your application's view | llm.message_published |
| Show that a run began | llm.generation_started |
| Observe a tool being dispatched or completing | llm.tool_call_started, llm.tool_call_completed |
A new-message event and a run-completed event can concern the same turn. Assign each a distinct job so they do not trigger the same business action twice. Pending approvals currently require the approval lookup flow; llm.tool_call_approval_required is not delivered as a webhook.
The event catalog contains exact event names, fields and delivery headers. For updates to an open conversation screen, see streaming availability.
Keep the workflow working as your app changes
Section: DOC-IN-webhooks#concepts.
Save the endpoint and subscription identities with your application's webhook configuration. There is one live subscription per endpoint. To change its event selection, replace the subscription; the gap does not receive events. If you need continuity, plan an overlap using a separate endpoint and deduplicate shared events before cutting over.
Use delivery history to recover retained failed deliveries. Neither changing a subscription nor re-enabling a receiver proves that missed events have replayed.
Next recipes and reference
Section: DOC-IN-webhooks#related.
- Receive and process the first completion event
- Recover a missing backend update
- Send a notification to a person
- Webhook API reference
Document ID: DOC-IN-webhooks. Section identities and revisions.