Skip to main content

Receive a completed order summary in your backend

Section ID: Guide/j9uvchaofm#create-endpoints-and-subscriptions

Associate an assistant run with an order in your application, then update that order when the run finishes. Keep the run identifier with the order so your backend can reconcile the result. This recipe uses an application-owned receiver and worker, the endpoint/subscription APIs, and the declared generation lifecycle.

Prepare an HTTPS receiver and a backend API credential. Keep endpoint credentials on the backend. Configure and verify the receiving integration before using it for order changes.

1. Register the receiver for completed runs​

Section ID: Guide/j9uvchaofm#create-an-endpoint

Use Create a webhook endpoint with your HTTPS receiving URL. Supply eventTypes for the subscription you want to create, and retain the returned endpoint and subscription identifiers. An endpoint without an event selection needs a subscription before it can receive the configured events.

Save the signing secret​

Section ID: Guide/j9uvchaofm#list-endpoints

Store the endpoint secret in your backend credential store. Use List webhook endpoints to find your endpoint by its returned identifier. Keep the listing and credentials private; do not send them to application users.

2. Accept verified events before updating the order​

Section ID: Guide/j9uvchaofm#verify-the-signature

Verify the incoming request with the endpoint secret and the receiver signature procedure. Preserve the original request bytes before parsing JSON. Reject an invalid signature, an unknown delivery format or an unexpected scope.

Persist the authenticated event identity, payload digest and pending work before returning 2xx. Acknowledge an identical duplicate without scheduling the order update again. If durable acceptance fails, return a non-success response so the delivery can be retried according to its configured policy.

Use the run identifier to find the associated order and inspect the generation completion fields. Mark a summary ready only for a successful outcome. Handle errors and context-compaction outcomes separately. Keep your application’s own operation identity for external effects; receipt deduplication alone does not make an order update happen exactly once.

3. Prove that the order reaches the right result​

Section ID: Guide/j9uvchaofm#list-subscriptions

Use List webhook subscriptions to inspect the configured endpoint selection before testing.

Inspect the subscription for the new endpoint before testing:

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 ID: Guide/j9uvchaofm#managing-endpoints

Use the following variations after the first completion workflow works.

Move to a new receiving URL​

Section ID: Guide/j9uvchaofm#update-an-endpoint

Use Update a webhook endpoint for the replacement receiving URL after testing it.

Deploy and test the new receiver, with its configured verification credentials and deduplication records, before changing the saved URL:

Nonempty name, URL and description replace the corresponding stored values; empty strings do not clear fields. There is no public revision precondition, so concurrent changes can overwrite one another. Verify the receiving configuration before retiring the old receiver.

Change which events the receiver handles​

Section ID: Guide/j9uvchaofm#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 ID: Guide/j9uvchaofm#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 ID: Guide/j9uvchaofm#delete-an-endpoint

Use Delete a webhook endpoint when retiring this integration.

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

Deleting the endpoint removes it and its associated provider subscriptions. Already dispatched deliveries can still reach the receiver; deletion does not establish erasure of historical deliveries or backups. Keep any application work already accepted by your receiver under your own cleanup and reconciliation process.

Event catalog​

Section ID: Guide/j9uvchaofm#receiver-event-catalog

See Event catalog in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Webhook events​

Section ID: Guide/j9uvchaofm#receiver-webhook-events

See Webhook events in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Delivery envelope​

Section ID: Guide/j9uvchaofm#receiver-delivery-envelope

See Delivery envelope in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Event types​

Section ID: Guide/j9uvchaofm#receiver-event-types

See Event types in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Payload shapes​

Section ID: Guide/j9uvchaofm#receiver-payload-shapes

See Payload shapes in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

llm.message_published​

Section ID: Guide/j9uvchaofm#receiver-llmmessage_published

See llm.message_published in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

llm.generation_started​

Section ID: Guide/j9uvchaofm#receiver-llmgeneration_started

See llm.generation_started in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

llm.generation_completed​

Section ID: Guide/j9uvchaofm#receiver-llmgeneration_completed

See llm.generation_completed in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Values of status​

Section ID: Guide/j9uvchaofm#receiver-llm-generation-completed-values-status

See Values of status in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

llm.tool_call_started​

Section ID: Guide/j9uvchaofm#receiver-llmtool_call_started

See llm.tool_call_started in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

llm.tool_call_completed​

Section ID: Guide/j9uvchaofm#receiver-llmtool_call_completed

See llm.tool_call_completed in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Approval waits​

Section ID: Guide/j9uvchaofm#receiver-llmtool_call_approval_required

See Approval waits in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Conversation updates​

Section ID: Guide/j9uvchaofm#receiver-conversation-updates

See Conversation updates in the event catalog for the delivery contract and payload reference. Continue with verifying the subscription outcome for this receiver recipe.

Document ID: Guide/j9uvchaofm