Lesson 7.2. Webhooks and Action Scheduler

Goal

Send and receive webhooks securely and run background work through Action Scheduler.

Key concepts

  • A WooCommerce webhook: topic (order.created, product.updated), delivery URL, secret
  • Signature: the X-WC-Webhook-Signature header = base64( HMAC-SHA256( body, secret ) )
  • Webhook delivery goes through Action Scheduler (the woocommerce-webhooks group); a failed delivery isn't retried, and after 5 failures in a row the webhook is disabled
  • Action Scheduler: as_enqueue_async_action(), as_schedule_single_action(), as_schedule_recurring_action()
  • Groups, unique jobs, statuses (pending, running, complete, failed), an error log
  • UI: Tools → Scheduled Actions; CLI: wp action-scheduler

Diagram

sequenceDiagram
  participant WC as WooCommerce
  participant AS as Action Scheduler
  participant R as Receiver
  WC->>AS: order.created → delivery job
  AS->>R: POST body + X-WC-Webhook-Signature
  R->>R: hash_equals(base64(hmac)), idempotency
  R-->>AS: 200
  AS->>WC: delivery status in the webhook log

Code

Checking the signature on the receiver side (PHP):

PHP
<?php
$body      = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$expected  = base64_encode( hash_hmac( 'sha256', $body, getenv( 'WC_WEBHOOK_SECRET' ), true ) );

if ( ! hash_equals( $expected, $signature ) ) {
	http_response_code( 401 );
	exit;
}

$event_id = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? '';
// store $event_id and skip repeats

A recurring job — the nightly stock sync:

PHP
<?php
add_action( 'init', static function () {
	if ( function_exists( 'as_has_scheduled_action' ) && ! as_has_scheduled_action( 'my_stock_sync' ) ) {
		as_schedule_recurring_action( strtotime( 'tomorrow 03:00' ), DAY_IN_SECONDS, 'my_stock_sync', [], 'erp' );
	}
} );

add_action( 'my_stock_sync', static function () {
	$page = 1;
	do {
		$rows = My_Erp_Client::stock( $page++ ); // 200 items at a time
		foreach ( $rows as $row ) {
			as_enqueue_async_action( 'my_stock_update', [ 'sku' => $row['sku'], 'qty' => $row['qty'] ], 'erp' );
		}
	} while ( $rows );
} );

Common mistakes

SymptomCauseFix
The signature never matchesHMAC of parsed and re-encoded JSONCalculate it from the raw request body
The webhook disabled itself5 failed deliveries in a rowAnswer 200 fast, move processing to a queue; re-enable the webhook and catch up the missed orders through the REST API
A recurring job multipliesas_schedule_recurring_action without a checkas_has_scheduled_action() before scheduling

Weak and strong answer

Question: Why not WP-Cron for the stock sync?

Weak answer. WP-Cron will do too.

Strong answer. WP-Cron is triggered by visits and has no statuses, retries or log. Syncing thousands of items needs a queue: Action Scheduler splits the work into small jobs, runs them in batches, marks failures and lets you rerun them. WooCommerce already ships it, so the dependency is free.

Why the second is stronger: The candidate knows the limits of WP-Cron and the practical benefits of a queue.

Practice

In the terminal the receiver answers 500: find the pending deliveries, run them, see what happened to the webhook and turn it back on.

On your own site: create an order.created webhook to a test receiver (for example, a local script) and check the signature. Make the receiver answer 500 and watch the deliveries in Tools → Scheduled Actions: WooCommerce doesn't retry them, it counts the failures.

curl / wp — Module 7. APIs and Integrations

Interview Questions

Calculate base64_encode( hash_hmac( 'sha256', $raw_body, $secret, true ) ) and compare it with X-WC-Webhook-Signature using hash_equals().

A job queue library for WordPress, built into WooCommerce. Jobs are stored in the database, have groups, statuses and a log, and run in batches through WP-Cron, an async request or WP-CLI.

Disable WP-Cron (DISABLE_WP_CRON) and run wp cron event run --due-now and/or wp action-scheduler run from the system cron.

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.