How to add custom fields to WooCommerce webhooks?

Webhooks are one of the most common ways to integrate two apps or services between each other. Basically, a webhook is a notification that a certain event was triggered. Every webhook consists of the data about the event and the URL to which the data should be sent.

Earlier, we’ve already discussed how to add custom params to WooCommerce REST API requests. Just like many other parts of WooCommerce, the WooCommerce webhooks can be customized and modified through actions and filters.

So, as you might have guessed, today, I’m going to show you how to add custom fields to WooCommerce webhooks.

Introduction

For example, if you choose the Order created topic (event), here’s a piece of the JSON code you’ll receive on your Delivery URL:

{
  "id": 70,
  "parent_id": 0,
  "status": "processing",
  "currency": "UAH",
  "version": "6.5.1",
  "prices_include_tax": false,
  "date_created": "2022-05-24T04:23:51",
  "date_modified": "2022-05-24T04:23:51",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "0.00",
  "shipping_tax": "0.00",
  "cart_tax": "0.00",
  "total": "55.00",
  "total_tax": "0.00"
...

This JSON object contains different data about the new order. And we can modify it by adding our own field here.

So, in this post, I’m going to show you how to add custom fields to the payload objects. To make this tutorial more realistic, here’s the goal we’ll try to achieve:

• We’ve got two customer groups: premium and non-premium
• In the webhook payload, I want to check if the custom is premium
• One of the ways to do this is to add a new field to the customer object
• We’re going to add the customer_is_premium field with the boolean value
• The value of the customer_is_premium field will depend on the customer’s meta field

Let’s get started!

How to modify the payload object?

There are many different ways of implementing the logic of splitting users into groups. In our case, we’ve got two groups: premium and non-premium (or regular).

Since we need this logic to demonstrate how to modify webhook payload objects, I’ll go the easiest way: we’ll work with the is_premium user meta field. This field will be boolean, so its value will be true or false.

To add custom fields to WooCommerce webhooks, we can use the woocommerce_webhook_payload filter hook. This filter’s handlers accept four parameters: the payload object, the current resource’s name, the resource’s ID, and the webhook’s ID.

However, we’ll need only two first parameters to modify webhook payloads.

We need to modify orders’ payloads, so, first of all, in our function, we need to check if the current resource is order.

add_filter( 'woocommerce_webhook_payload', 'my_woocommerce_webhook_payload', 10, 4 );
function my_woocommerce_webhook_payload( $payload, $resource, $resource_id, $id ) {
	if ( $resource !== 'order' ) {
		return $payload;
	}

	// Our logic will be here

	return $payload;
}

The payload object is a regular PHP associative array, so we can easily modify it.

add_filter( 'woocommerce_webhook_payload', 'modify_order_webhook_payload', 10, 4 );
function modify_order_webhook_payload( $payload, $resource, $resource_id, $id ) {
	if ( $resource !== 'order' ) {
		return $payload;
	}

	$customer_is_premium = false;
	$customer_id = (int) $payload['customer_id'];

	// All guest users will have the customer_id field set to 0
	if ( $customer_id > 0 ) {
		$customer_is_premium = (boolean) get_user_meta( $customer_id, 'is_premium', true );
	}

	$payload['customer_is_premium'] = $customer_is_premium;

	return $payload;
}

Now, if I check the payload of the new order, I’ll see my new field at the end of the object:

  ...
  "_links": {
    "self": [
      {
        "href": "https://test.com/wp-json/wc/v3/orders/81"
      }
    ],
    "collection": [
      {
        "href": "https://test.com/wp-json/wc/v3/orders"
      }
    ],
    "customer": [
      {
        "href": "https://test.com/wp-json/wc/v3/customers/1"
      }
    ]
  },
  "customer_is_premium": true
}

So, I guess you get the idea: if you’ll need to modify user payloads or coupon payloads, just check the current resource and add your fields to the $payload array.

The same logic can be applied if you need to change any already existing fields.

How to add product categories to the order webhook payloads

This section was a added almost a year after this post was published. I received a lot of questions about how to add custom fields to the order line items to the order webhook payloads. So I decided to update this post with an additional code snippet that’s gonna be helpful for anyone who wants to add some more info about the order items:

add_filter( 'woocommerce_webhook_payload', 'add_categories_to_order_payload', 99, 4 );
function add_categories_to_order_payload( $payload, $resource, $resource_id, $event ) {
  if ( $resource !== 'order' ) {
      return $payload;
  }

  $line_items = $payload['line_items'];
  $updated_line_items = [];

  foreach ( $line_items as $line_item ) {
      $product_id = $line_item['product_id'];
      $product_categories = get_the_terms( $product_id, 'product_cat' );
      $updated_line_item = $line_item;

      if ( ! empty( $product_categories ) ) {
          $category_names = wp_list_pluck( $product_categories, 'name' );
          $updated_line_item['categories'] = $category_names;
      } else {
          $updated_line_item['categories'] = [];
      }

      $updated_line_items[] = $updated_line_item;
  }

  $payload['line_items'] = $updated_line_items;

  return $payload;
}

In this specific example, we’re iterating through the line_items array and get a list of the categories of each product. I used the wp_list_pluck() function to keep only the category names in the array. However, keep in mind that the get_the_terms() function returns an array of WP_Term objects.

You can also replace the wp_list_pluck() function with the array_map() function if you prefer to use the core functions.

Summary

As you see, all you need to modify WooCommerce webhook payloads is to know the right hook 🙂

I hope you found the answers you were looking for. Otherwise, feel free to write about your issues in the comments or even contact me directly.

Don’t forget to follow me on LinkedIn to stay updated with new posts and tweets on things I learn or do.

Thank you for your attention; see you in the next one!