Skip to main content

Receive a completed order summary in your backend

Section: DOC-IN-webhooks-endpoints#create-endpoints-and-subscriptions.

Connect an assistant run to an order in your application, then update that order when the run finishes. This recipe creates one endpoint subscribed to completion events and verifies that an event reaches your application. Travila supplies the run event; your application supplies the order record, receiver and background worker.

Before starting, prepare an HTTPS receiving route, a backend API key, and a conversation you can use for a test run. Keep the receiver's signing secret and API key on the backend. These configuration calls do not need X-On-Behalf-Of.

1. Register the receiver for completed runs​

Section: DOC-IN-webhooks-endpoints#create-an-endpoint.

Create the endpoint with eventTypes so that the subscription is created in the same call. Replace the example URL with your receiver:

curl -X POST https://api.travila.ai/api/v1/webhooks/create-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "orders-service",
  "url": "https://api.example.com/hooks/travila",
  "description": "Order pipeline consumer",
  "eventTypes": [
    "llm.generation_completed"
  ]
}'

Reference: Create a webhook endpoint · Request fields.

Save the returned endpoint and subscription IDs. The URL must point to your receiver; orders-service is simply this recipe's name for it. An endpoint created without eventTypes receives nothing until you create its subscription.

Save the signing secret​

Section: DOC-IN-webhooks-endpoints#list-endpoints.

Store the endpoint's secret in your backend's credential store. If you did not retain it at creation, retrieve your endpoint through list-endpoints:

curl -X POST https://api.travila.ai/api/v1/webhooks/list-endpoints \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "page": 1,
  "perPage": 25
}'

Reference: List webhook endpoints · Request fields.

Find your endpoint by its returned ID and read its secret. Do not expose the listing or signing secret to your application's users.

2. Accept verified events before updating the order​

Section: DOC-IN-webhooks-endpoints#verify-the-signature.

Have your receiver verify the incoming request using its endpoint secret and the signature contract in the event reference. Verification needs the original request bytes, so preserve them before parsing JSON. Reject an invalid signature or a delivery for an unexpected scope.

After verification, use the signed event identity to recognize duplicates. Save the event and pending work durably before returning 2xx; acknowledge an identical duplicate without scheduling the order update again. If durable acceptance fails, return a non-success response so delivery can be retried.

Your worker then uses the event's run ID to find the order your application associated with that run. Inspect the completion status: only make the summary ready when the run succeeded. An error or context-compaction outcome needs its own application handling. Use generation outcomes to recover the run's state when necessary.

For order updates that can have external effects, retain your application's own operation identity as well. Deduplicating webhook receipt does not itself make an external action happen exactly once.

3. Prove that the order reaches the right result​

Section: DOC-IN-webhooks-endpoints#list-subscriptions.

Inspect the subscription for the new endpoint before testing:

curl -X POST https://api.travila.ai/api/v1/webhooks/list-subscriptions \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "endpointId": "ep_abc123",
  "page": 1,
  "perPage": 25
}'

Reference: List webhook subscriptions · Request fields.

Confirm that its eventTypes includes llm.generation_completed. Start one ordinary assistant run, saving the returned run ID with a test order in your application.

Check delivery history, then inspect your own order record. The completed recipe has a matching run outcome, a durably accepted event and the intended order update. Also send an identical delivery to your local handler test: it must not repeat the update. Test an unsuccessful run separately so your UI does not show a failed summary as ready.

Change the receiver when your application moves​

Section: DOC-IN-webhooks-endpoints#managing-endpoints.

Use the following variations after the first completion workflow works.

Move to a new receiving URL​

Section: DOC-IN-webhooks-endpoints#update-an-endpoint.

Deploy and test the new receiver, with access to the signing secret and deduplication records, before changing the saved URL:

curl -X POST https://api.travila.ai/api/v1/webhooks/update-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "endpointId": "ep_abc123",
  "url": "https://api.example.com/hooks/travila-v2"
}'

Reference: Update a webhook endpoint · Request fields.

Only supplied fields change. Verify a new delivery at the new URL before retiring the old receiver. This update does not change the event subscription.

Change which events the receiver handles​

Section: DOC-IN-webhooks-endpoints#one-subscription-per-endpoint.

Plan a deliberate cutover when changing event selection. Check the current subscription before replacing it so the receiver’s gap or overlap is understood.

For a cutover that needs overlap, create a separate endpoint with the new event selection, deduplicate authenticated events across both receivers, verify the new path, and retire the old subscription. A second subscription on the same endpoint is rejected. Events published in a replacement gap are not delivered to that endpoint.

Use your deployment's own subscription name​

Section: DOC-IN-webhooks-endpoints#addressing-a-subscription-with-your-own-id.

Use an application-owned subscription name when that makes deployment recovery clearer. Save the created subscription identity with the name.

Deletion frees that name for reuse. Keep a record of which deployment the name currently identifies so recovery does not confuse an old subscription with its replacement.

Retire this order-summary integration​

Section: DOC-IN-webhooks-endpoints#delete-an-endpoint.

Stop assigning new work to this integration and inspect the delivery history you need to retain. Then delete the endpoint:

curl -X POST https://api.travila.ai/api/v1/webhooks/delete-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "endpointId": "ep_abc123"
}'

Reference: Delete a webhook endpoint · Request fields.

A successful delete returns an empty body and removes the endpoint and its subscriptions. Its delivery history cannot be replayed afterward. Keep any application work already accepted by your receiver under your own cleanup and reconciliation process.

For credential rotation and exact signature fields, use the event reference. For missing updates, continue with Recover a missing backend update.

Document ID: DOC-IN-webhooks-endpoints. Section identities and revisions.