UCP Webhooks for Agent Commerce: Real-Time Fulfillment Without Polling

One of the first things a commerce agent needs to do after placing an order is track that order to completion. In traditional integrations, this is done through polling — the system repeatedly calls the merchant’s order status endpoint until the status changes. In agentic commerce at scale, polling is expensive, slow, and brittle. UCP’s webhook architecture eliminates the need for polling by pushing fulfillment events to the agent in real time.

The Polling Problem at Agent Scale

A single human shopper tracking one order places minimal load on a merchant’s order status API. At agent scale — thousands of concurrent orders being tracked by automated systems — polling creates API quota exhaustion, rate limiting failures, and unnecessary compute cost on both sides of the connection. Agents waiting for order confirmations may time out before the next poll cycle, creating uncertainty about transaction state.

How UCP Webhooks Work

When a UCP order is placed, the agent registers a webhook endpoint to receive fulfillment events. The merchant’s UCP implementation sends event notifications to this endpoint as the order progresses: order confirmed, payment captured, items picked, shipped, out for delivery, delivered. Each event is signed with the merchant’s UCP key, allowing the agent to verify authenticity before updating its internal state.

Event Types in the UCP Fulfillment Webhook Schema

UCP defines a standard set of fulfillment event types that all certified merchants must support: ORDER_CONFIRMED, PAYMENT_CAPTURED, FULFILLMENT_STARTED, SHIPMENT_CREATED (with tracking number), OUT_FOR_DELIVERY, DELIVERED, RETURN_INITIATED, RETURN_COMPLETED, REFUND_ISSUED. Merchants may emit additional custom events using the UCP extension schema, but the core set is guaranteed for all UCP-certified integrations.

Handling Webhook Delivery Failures

Networks fail. Webhook endpoints go down. UCP’s webhook specification includes retry logic requirements: merchants must retry failed webhook deliveries with exponential backoff for a minimum of 24 hours. Agents must expose idempotent webhook handlers that can receive duplicate events without creating duplicate state changes. The combination of retry-capable delivery and idempotent handlers creates a reliable event stream even across network failures.

Frequently Asked Questions

Can an agent poll for order status if it does not have a public webhook endpoint?

Yes. UCP supports both webhook push and polling pull models. However, the polling rate is throttled per the merchant’s rate limit policy. Webhooks are strongly recommended for any agent handling more than a small number of concurrent orders.

Frequently Asked Questions