AI agent autonomous commerce workflow — UCP protocol visualization

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

Last Updated: November 10, 2026 • Autonomous Agentic Commerce Spec v2026-08-25

Production Validated

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

Fulfillment Event Legacy Polling Pattern UCP Webhook Architecture Payload Envelope Retry SLA Delivery Guarantee
Order Confirmation Agent polls /orders/{id} every 60 seconds generating server spikes. Immediate push event to agent fulfillment webhook URI. order.confirmed event with signed order envelope. Immediate (<50ms) push dispatch. At-least-once with idempotency key deduplication.
Stock Reservation Periodic checking of cart reservation status. Event dispatch upon inventory lock acquisition or failure. inventory.reserved or inventory.exhausted event. Sub-100ms notification delivery. Exactly-once processing via reservation UUID.
Payment Settlement Running background cron jobs to check payment processor logs. Asynchronous gateway clearing attestation delivered instantly. payment.settled with ISO 20022 message ID and receipt. Exponential backoff (1s, 5s, 30s, 5m, 1h). Cryptographic non-repudiation with audit logging.
Carrier Tracking Customer service screen scraping or automated tracking emails. Real-time carrier milestone dispatch with GPS coordinates. fulfillment.shipped with tracking number and carrier object. Real-time event stream on carrier status change. Instant ambient delivery notification to user device.
Return / Cancellation Manual customer support tickets and phone inquiries. Automated reverse-logistics RMA event dispatch. return.requested with pre-generated carrier return label. Sub-1 second event generation. Fully automated refund trigger upon carrier scan.

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

How are UCP webhook payloads cryptographically authenticated?

Each webhook payload includes an X-UCP-Signature HTTP header containing a millisecond timestamp and an HMAC-SHA256 signature generated using a shared merchant-agent secret key.

What retry policy does UCP mandate for failed webhook delivery attempts?

The protocol requires exponential backoff with jitter across at least 5 retry intervals (1s, 5s, 30s, 5min, 1hour) before routing the event to a Dead-Letter Queue (DLQ) for alerting.

How does the webhook consumer guarantee exactly-once processing?

Every event contains a globally unique event_id UUID; receivers check and write this ID to an in-memory Redis distributed store using SETNX with a 24-hour TTL before executing business logic.


Posted

in

by

Tags:

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *