AgenticWebhookManager.php at 11.1.0-rc.2 · WooCommerce

woocommerce / src / Internal / Admin / Agentic / AgenticWebhookManager.php

AgenticWebhookManager.php

300 lines 8.2 KB

Raw Download Zip

1	<?php
2	declare(strict_types=1);
3
4	namespace Automattic\WooCommerce\Internal\Admin\Agentic;
5
6	use Automattic\WooCommerce\Enums\OrderStatus;
7	use Automattic\WooCommerce\Internal\RegisterHooksInterface;
8	use Automattic\WooCommerce\StoreApi\Routes\V1\Agentic\Enums\OrderMetaKey;
9	use WC_Order;
10	use WC_Webhook;
11
12	/**
13	* AgenticWebhookManager class
14	*
15	* Integrates Agentic Commerce Protocol webhooks with WooCommerce's native webhook system.
16	* Defines custom action topics and handles filtering/transformation for ACP compliance.
17	*
18	* @since 10.3.0
19	*/
20	class AgenticWebhookManager implements RegisterHooksInterface {
21	/**
22	* Action that will be triggered for webhooks.
23	*
24	* @var string
25	*/
26	const WEBHOOK_ACTION = 'woocommerce_agentic_order_changed';
27
28	/**
29	* Topic that will be used for webhooks.
30	*
31	* @var string
32	*/
33	const WEBHOOK_TOPIC = 'action.' . self::WEBHOOK_ACTION;
34
35	/**
36	* Meta key to store if the first event has been delivered.
37	*
38	* @var string
39	*/
40	const FIRST_EVENT_DELIVERED_META_KEY = '_acp_order_created_sent';
41
42	/**
43	* Payload builder instance.
44	*
45	* @var AgenticWebhookPayloadBuilder
46	*/
47	private $payload_builder;
48
49	/**
50	* Initializes dependencies and hooks.
51	*
52	* @internal
53	*
54	* @param AgenticWebhookPayloadBuilder $payload_builder Payload builder instance.
55	*/
56	final public function init( AgenticWebhookPayloadBuilder $payload_builder ) {
57	$this->payload_builder = $payload_builder;
58	}
59
60	/**
61	* Initialize hooks for webhook integration.
62	*
63	* @internal
64	*/
65	public function register() {
66
67	add_filter( 'woocommerce_webhook_topics', array( $this, 'register_webhook_topic_names' ) );
68
69	// Hook into order lifecycle events to fire our custom actions.
70	add_action( 'woocommerce_new_order', array( $this, 'handle_order_created' ), 999, 2 ); // Hook late to give a chance for other plugins to modify.
71	add_action( 'woocommerce_order_status_changed', array( $this, 'handle_order_status_changed' ), 10, 4 );
72	add_action( 'woocommerce_order_refunded', array( $this, 'handle_order_refunded' ), 10, 1 );
73
74	// Customize webhook payload for our topics.
75	add_filter( 'woocommerce_webhook_payload', array( $this, 'customize_webhook_payload' ), 10, 4 );
76
77	// Customize webhook HTTP arguments for our topics.
78	add_filter( 'woocommerce_webhook_http_args', array( $this, 'customize_webhook_http_args' ), 10, 3 );
79
80	// When the webhook is delivered (or not), mark the first event as delivered.
81	add_action( 'woocommerce_webhook_delivery', array( $this, 'mark_first_event_delivered' ), 10, 5 );
82	}
83
84	/**
85	* Register webhook topic names for display in the UI.
86	*
87	* @param array $topics Existing topics.
88	* @return array Modified topics.
89	*/
90	public function register_webhook_topic_names( $topics ): array {
91	$topics[ self::WEBHOOK_TOPIC ] = __( 'Agentic Commerce Protocol: Order created or updated', 'woocommerce' );
92	return $topics;
93	}
94
95	/**
96	* Handle order creation.
97	*
98	* @param int $order_id Order ID.
99	* @param WC_Order $order Order object.
100	*/
101	public function handle_order_created( $order_id, $order ) {
102	if ( ! $this->should_trigger_webhook( $order ) ) {
103	return;
104	}
105
106	/**
107	* Fires when an Agentic order is updated or created.
108	*
109	* @since 10.3.0
110	*
111	* @param int $order_id Order ID.
112	* @param WC_Order $order Order object.
113	*/
114	do_action( self::WEBHOOK_ACTION, $order_id, $order );
115	}
116
117	/**
118	* Handle order status changes.
119	*
120	* @param int $order_id Order ID.
121	* @param string $old_status Old status.
122	* @param string $new_status New status.
123	* @param WC_Order $order Order object.
124	*/
125	public function handle_order_status_changed( $order_id, $old_status, $new_status, $order ) {
126	if ( ! $this->should_trigger_webhook( $order ) ) {
127	return;
128	}
129
130	/**
131	* Fires when an Agentic order status changes.
132	*
133	* @since 10.3.0
134	*
135	* @param int $order_id Order ID.
136	* @param WC_Order $order Order object.
137	*/
138	do_action( self::WEBHOOK_ACTION, $order_id, $order );
139	}
140
141	/**
142	* Handle order refunds.
143	*
144	* @param int $order_id Order ID.
145	*/
146	public function handle_order_refunded( $order_id ) {
147	$order = wc_get_order( $order_id );
148	if ( ! $order \|\| ! $this->should_trigger_webhook( $order ) ) {
149	return;
150	}
151
152	/**
153	* Fires when an Agentic order is refunded.
154	*
155	* @since 10.3.0
156	*
157	* @param int $order_id Order ID.
158	* @param WC_Order $order Order object.
159	*/
160	do_action( self::WEBHOOK_ACTION, $order_id, $order );
161	}
162
163	/**
164	* Check if webhook should be triggered for this order.
165	*
166	* @param WC_Order $order Order object.
167	* @return bool True if webhook should be triggered.
168	*/
169	private function should_trigger_webhook( $order ) {
170	// Only trigger for orders with an Agentic checkout session ID.
171	$checkout_session_id = $order->get_meta( OrderMetaKey::AGENTIC_CHECKOUT_SESSION_ID );
172	if ( empty( $checkout_session_id ) ) {
173	return false;
174	}
175
176	// Don't trigger for draft orders.
177	if (
178	in_array(
179	$order->get_status(),
180	array(
181	OrderStatus::CHECKOUT_DRAFT,
182	OrderStatus::DRAFT,
183	OrderStatus::AUTO_DRAFT,
184	),
185	true
186	)
187	) {
188	return false;
189	}
190
191	return true;
192	}
193
194	/**
195	* Customize webhook payload for Agentic topics.
196	*
197	* @param array $payload Original payload.
198	* @param string $resource_type Resource type.
199	* @param int $resource_id Resource ID.
200	* @param int $webhook_id Webhook ID.
201	* @return array Modified payload.
202	*/
203	public function customize_webhook_payload( $payload, $resource_type, $resource_id, $webhook_id ) {
204	$webhook = wc_get_webhook( $webhook_id );
205	if ( ! $webhook ) {
206	return $payload;
207	}
208
209	$topic = $webhook->get_topic();
210
211	// Check if this is one of our Agentic topics.
212	if ( self::WEBHOOK_TOPIC !== $topic ) {
213	return $payload;
214	}
215
216	// Get the order.
217	$order = wc_get_order( $resource_id );
218	if ( ! $order ) {
219	return $payload;
220	}
221
222	$is_first_event = 'sent' !== $order->get_meta( self::FIRST_EVENT_DELIVERED_META_KEY );
223	$event = $is_first_event ? 'order_create' : 'order_update';
224
225	// Build ACP-compliant payload.
226	return $this->payload_builder->build_payload( $event, $order );
227	}
228
229	/**
230	* Customize webhook HTTP arguments for Agentic topics.
231	*
232	* @param array $http_args HTTP arguments.
233	* @param mixed $arg First hook argument.
234	* @param int $webhook_id Webhook ID.
235	* @return array Modified HTTP arguments.
236	*/
237	public function customize_webhook_http_args( $http_args, $arg, $webhook_id ) {
238	$webhook = wc_get_webhook( $webhook_id );
239	if ( ! $webhook ) {
240	return $http_args;
241	}
242
243	$topic = $webhook->get_topic();
244
245	// Check if this is one of our Agentic topics.
246	if ( self::WEBHOOK_TOPIC !== $topic ) {
247	return $http_args;
248	}
249
250	// Compute HMAC signature per ACP webhook spec using WooCommerce's built-in method.
251	// The signature must be computed over the raw request body.
252	if ( isset( $http_args['body'] ) && ! empty( $webhook->get_secret() ) ) {
253	// Use WooCommerce's signature generation to ensure consistency.
254	$signature = $webhook->generate_signature( $http_args['body'] );
255
256	// Add Merchant-Signature header per ACP webhook specification.
257	$http_args['headers']['Merchant-Signature'] = $signature;
258	}
259
260	return $http_args;
261	}
262
263	/**
264	* Mark first event as delivered on successful webhook delivery.
265	*
266	* @param array $http_args HTTP request args.
267	* @param mixed $response HTTP response.
268	* @param float $duration Request duration.
269	* @param int $arg First argument to the action (order_id).
270	* @param int $webhook_id Webhook ID.
271	*/
272	public function mark_first_event_delivered( $http_args, $response, $duration, $arg, $webhook_id ) {
273	// Only proceed for successful responses.
274	if ( is_wp_error( $response ) ) {
275	return;
276	}
277	$code = wp_remote_retrieve_response_code( $response );
278	if ( $code < 200 \|\| $code >= 300 ) {
279	return;
280	}
281
282	// Verify this is our webhook topic.
283	$webhook = wc_get_webhook( $webhook_id );
284	if ( ! $webhook \|\| self::WEBHOOK_TOPIC !== $webhook->get_topic() ) {
285	return;
286	}
287
288	// $arg contains the order_id from do_action( self::WEBHOOK_ACTION, $order_id, $order ).
289	$order = wc_get_order( $arg );
290	if ( ! $order ) {
291	return;
292	}
293
294	if ( 'sent' !== $order->get_meta( self::FIRST_EVENT_DELIVERED_META_KEY ) ) {
295	$order->update_meta_data( self::FIRST_EVENT_DELIVERED_META_KEY, 'sent' );
296	$order->save();
297	}
298	}
299	}
300