WooCommerce Code Reference

WC_Webhook extends WC_Legacy_Webhook
in package

Webhook class.

Implemented by classes using the same CRUD(s) pattern.

Table of Contents

$cache_group  : string
Stores meta in cache for future reads.
$changes  : array
Core data changes for this object.
$data  : array
Stores webhook data.
$data_store  : object
Contains a reference to the data store for this class.
$default_data  : array
Set to _data on construct so we can track and reset data if needed.
$extra_data  : array
Extra data for this object. Name value pairs (name + default value).
$id  : int
ID for this object.
$meta_data  : array
Stores additional meta data.
$object_read  : bool
This is false until the object is read from the DB.
$object_type  : string
This is the name of this object type.
$processed  : array
Store which object IDs this webhook has processed (ie scheduled to be delivered) within the current page request.
__clone()  : mixed
When the object is cloned, make sure meta is duplicated correctly.
__construct()  : mixed
Load webhook data based on how WC_Webhook is called.
__get()  : mixed
Magic __get method for backwards compatibility. Maps legacy vars to new getters.
__isset()  : bool
Magic __isset method for backwards compatibility. Legacy properties which could be accessed directly in the past.
__sleep()  : array
Only store the object ID to avoid serializing the data object instance.
__toString()  : string
Change data to JSON format.
__wakeup()  : mixed
Re-run the constructor with the object ID.
add_meta_data()  : mixed
Add meta data.
apply_changes()  : mixed
Merge changes with data and clear.
build_payload()  : mixed
Build the payload data for the webhook.
delete()  : bool
Delete an object, set the ID to 0, and return result.
delete_meta_data()  : mixed
Delete meta data.
delete_meta_data_by_mid()  : mixed
Delete meta data.
deliver()  : mixed
Deliver the webhook payload using wp_safe_remote_request().
deliver_ping()  : bool|WP_Error
Send a test ping to the delivery URL, sent when the webhook is first created.
enqueue()  : mixed
Enqueue the hooks associated with the webhook.
generate_signature()  : string
Generate a base64-encoded HMAC-SHA256 signature of the payload body so the.
get_api_version()  : string
API version.
get_changes()  : array
Return data changes only.
get_data()  : array
Returns all data for this object.
get_data_keys()  : array
Returns array of expected data keys for this object.
get_data_store()  : object
Get the data store.
get_date_created()  : WC_DateTime|null
Get webhook created date.
get_date_modified()  : WC_DateTime|null
Get webhook modified date.
get_delivery_log()  : void
Get the delivery log specified by the ID. The delivery log includes:
get_delivery_logs()  : string
Get the delivery logs for this webhook.
get_delivery_url()  : string
Get the delivery URL.
get_event()  : string
Get the event for the webhook, e.g. `created`.
get_extra_data_keys()  : array
Returns all "extra" data keys for an object (for sub objects like product types).
get_failure_count()  : int
Get the failure count.
get_hooks()  : array
Get the hook names for the webhook.
get_i18n_status()  : string
Get the webhook i18n status.
get_id()  : int
Returns the unique ID for this object.
get_meta()  : mixed
Get Meta Data by Key.
get_meta_data()  : array
Get All Meta Data.
get_name()  : string
Get the friendly name for the webhook.
get_new_delivery_id()  : string
Generate a new unique hash as a delivery id based on current time and wehbook id.
get_object_read()  : bool
Get object read property.
get_pending_delivery()  : bool
Get pending delivery.
get_post_data()  : null|WP_Post
Get the post data for the webhook.
get_resource()  : string
Get the resource for the webhook, e.g. `order`.
get_secret()  : string
Get the secret used for generating the HMAC-SHA256 signature.
get_status()  : string
Get the webhook status.
get_topic()  : string
Get the webhook topic, e.g. `order.created`.
get_user_id()  : int
Get the user ID for this webhook.
log_delivery()  : mixed
Log the delivery request/response.
meta_exists()  : bool
See if meta data exists, since get_meta always returns a '' or array().
process()  : mixed
Process the webhook for delivery by verifying that it should be delivered.
read_meta_data()  : mixed
Read Meta Data from the database. Ignore any internal properties.
save()  : int
Save should create or update based on object existence.
save_meta_data()  : mixed
Update Meta Data in the database.
set_api_version()  : mixed
Set API version.
set_date_created()  : mixed
Set webhook created date.
set_date_modified()  : mixed
Set webhook modified date.
set_defaults()  : mixed
Set all props to default values.
set_delivery_url()  : mixed
Set the delivery URL.
set_failure_count()  : mixed
Set failure count.
set_id()  : mixed
Set ID.
set_meta_data()  : mixed
Set all meta data from array.
set_name()  : mixed
Set webhook name.
set_object_read()  : mixed
Set object read property.
set_pending_delivery()  : mixed
Set pending delivery.
set_props()  : bool|WP_Error
Set a collection of props in one go, collect any errors, and return the result.
set_secret()  : mixed
Set the secret used for generating the HMAC-SHA256 signature.
set_status()  : mixed
Set status.
set_topic()  : mixed
Set the webhook topic and associated hooks.
set_user_id()  : mixed
Set user ID.
update_meta_data()  : mixed
Update meta data by key or ID, if provided.
update_status()  : mixed
Update the webhook status.
error()  : mixed
When invalid data is found, throw an exception unless reading from the DB.
filter_null_meta()  : bool
Filter null meta values from array.
get_hook_prefix()  : string
Prefix for action and filter hooks on data.
get_prop()  : mixed
Gets a prop for a getter method.
is_already_processed()  : bool
Checks if the specified resource has already been queued for delivery within the current request.
is_internal_meta_key()  : bool
Check if the key is an internal one.
maybe_read_meta_data()  : mixed
Read meta data if null.
set_date_prop()  : mixed
Sets a date prop whilst handling formatting and datetime objects.
set_prop()  : mixed
Sets a prop for a setter method.
failed_delivery()  : mixed
Track consecutive delivery failures and automatically disable the webhook.
get_legacy_api_payload()  : array
Get Legacy API payload.
get_topic_hooks()  : array
Get the associated hook names for a topic.
get_wp_api_payload()  : array
Get WP API integration payload.
is_active()  : bool
Returns if webhook is active.
is_valid_action()  : bool
Validates the criteria for certain actions.
is_valid_post_action()  : bool
Validates post actions.
is_valid_processing_action()  : bool
Validates WC processing actions.
is_valid_resource()  : bool
Checks the resource for this webhook is valid e.g. valid post status.
is_valid_topic()  : bool
Returns if topic is valid.
is_valid_user_action()  : bool
Validates user actions.
should_deliver()  : bool
Helper to check if the webhook should be delivered, as some hooks.

Properties

$data

Stores webhook data.

protected array $data = array('date_created' => ull, 'date_modified' => ull, 'status' => 'disabled', 'delivery_url' => '', 'secret' => '', 'name' => '', 'topic' => '', 'hooks' => '', 'resource' => '', 'event' => '', 'failure_count' => 0, 'user_id' => 0, 'api_version' => 3, 'pending_delivery' => alse)

$extra_data

Extra data for this object. Name value pairs (name + default value).

protected array $extra_data = array()

Used as a standard way for sub classes (like product types) to add additional information to an inherited class.

Tags
since
3.0.0

$processed

Store which object IDs this webhook has processed (ie scheduled to be delivered) within the current page request.

protected array $processed = array()

Methods

__construct()

Load webhook data based on how WC_Webhook is called.

public __construct(WC_Webhook|int $data) : mixed
Parameters
$data : WC_Webhook|int

Webhook ID or data.

Tags
throws
Exception

If webhook cannot be read/found and $data is set.

Return values
mixed

__get()

Magic __get method for backwards compatibility. Maps legacy vars to new getters.

public __get(string $key) : mixed
Parameters
$key : string

Item to get.

Return values
mixed

__isset()

Magic __isset method for backwards compatibility. Legacy properties which could be accessed directly in the past.

public __isset(string $key) : bool
Parameters
$key : string

Item to check.

Return values
bool

add_meta_data()

Add meta data.

public add_meta_data(string $key, string|array $value[, bool $unique = false ]) : mixed
Parameters
$key : string

Meta key.

$value : string|array

Meta value.

$unique : bool = false

Should this be a unique key?.

Tags
since
2.6.0
Return values
mixed

build_payload()

Build the payload data for the webhook.

public build_payload(mixed $resource_id) : mixed
Parameters
$resource_id : mixed

First hook argument, typically the resource ID.

Tags
since
2.2.0
Return values
mixedPayload data.

delete()

Delete an object, set the ID to 0, and return result.

public delete([bool $force_delete = false ]) : bool
Parameters
$force_delete : bool = false

Should the date be deleted permanently.

Tags
since
2.6.0
Return values
boolresult

delete_meta_data()

Delete meta data.

public delete_meta_data(string $key) : mixed
Parameters
$key : string

Meta key.

Tags
since
2.6.0
Return values
mixed

delete_meta_data_by_mid()

Delete meta data.

public delete_meta_data_by_mid(int $mid) : mixed
Parameters
$mid : int

Meta ID.

Tags
since
2.6.0
Return values
mixed

deliver()

Deliver the webhook payload using wp_safe_remote_request().

public deliver(mixed $arg) : mixed
Parameters
$arg : mixed

First hook argument.

Tags
since
2.2.0
Return values
mixed

deliver_ping()

Send a test ping to the delivery URL, sent when the webhook is first created.

public deliver_ping() : bool|WP_Error
Tags
since
2.2.0
Return values
bool|WP_Error

enqueue()

Enqueue the hooks associated with the webhook.

public enqueue() : mixed
Tags
since
2.2.0
Return values
mixed

generate_signature()

Generate a base64-encoded HMAC-SHA256 signature of the payload body so the.

public generate_signature(string $payload) : string

recipient can verify the authenticity of the webhook. Note that the signature. is calculated after the body has already been encoded (JSON by default).

Parameters
$payload : string

Payload data to hash.

Tags
since
2.2.0
Return values
string

get_api_version()

API version.

public get_api_version([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
string

get_date_created()

Get webhook created date.

public get_date_created([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.2.0
Return values
WC_DateTime|nullObject if the date is set or null if there is no date.

get_date_modified()

Get webhook modified date.

public get_date_modified([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.2.0
Return values
WC_DateTime|nullObject if the date is set or null if there is no date.

get_delivery_log()

Get the delivery log specified by the ID. The delivery log includes:

public get_delivery_log(int $delivery_id) : void
  • duration
  • summary
  • request method/url
  • request headers/body
  • response code/message/headers/body
Parameters
$delivery_id : int

Delivery ID.

Tags
since
2.2
deprecated
3.3.0

get_delivery_logs()

Get the delivery logs for this webhook.

public get_delivery_logs() : string
Tags
since
3.3.0
Return values
string

get_delivery_url()

Get the delivery URL.

public get_delivery_url([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
string

get_event()

Get the event for the webhook, e.g. `created`.

public get_event() : string
Tags
since
2.2.0
Return values
string

get_extra_data_keys()

Returns all "extra" data keys for an object (for sub objects like product types).

public get_extra_data_keys() : array
Tags
since
3.0.0
Return values
array

get_failure_count()

Get the failure count.

public get_failure_count([string $context = 'view' ]) : int
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
int

get_hooks()

Get the hook names for the webhook.

public get_hooks() : array
Tags
since
2.2.0
Return values
array

get_meta()

Get Meta Data by Key.

public get_meta([string $key = '' ][, bool $single = true ][, string $context = 'view' ]) : mixed
Parameters
$key : string = ''

Meta Key.

$single : bool = true

return first found meta with key, or all with $key.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
2.6.0
Return values
mixed

get_name()

Get the friendly name for the webhook.

public get_name([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
string

get_new_delivery_id()

Generate a new unique hash as a delivery id based on current time and wehbook id.

public get_new_delivery_id() : string

Return the hash for inclusion in the webhook request.

Tags
since
2.2.0
Return values
string

get_pending_delivery()

Get pending delivery.

public get_pending_delivery([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.2.0
Return values
bool

get_resource()

Get the resource for the webhook, e.g. `order`.

public get_resource() : string
Tags
since
2.2.0
Return values
string

get_secret()

Get the secret used for generating the HMAC-SHA256 signature.

public get_secret([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
string

get_status()

Get the webhook status.

public get_status([string $context = 'view' ]) : string
  • 'active' - delivers payload.
  • 'paused' - does not deliver payload, paused by admin.
  • 'disabled' - does not delivery payload, paused automatically due to consecutive failures.
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
stringstatus

get_topic()

Get the webhook topic, e.g. `order.created`.

public get_topic([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
string

get_user_id()

Get the user ID for this webhook.

public get_user_id([string $context = 'view' ]) : int
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
2.2.0
Return values
int

log_delivery()

Log the delivery request/response.

public log_delivery(string $delivery_id, array $request, array|WP_Error $response, float $duration) : mixed
Parameters
$delivery_id : string

Previously created hash.

$request : array

Request data.

$response : array|WP_Error

Response data.

$duration : float

Request duration.

Tags
since
2.2.0
Return values
mixed

meta_exists()

See if meta data exists, since get_meta always returns a '' or array().

public meta_exists([string $key = '' ]) : bool
Parameters
$key : string = ''

Meta Key.

Tags
since
3.0.0
Return values
bool

process()

Process the webhook for delivery by verifying that it should be delivered.

public process(mixed $arg) : mixed

and scheduling the delivery (in the background by default, or immediately).

Parameters
$arg : mixed

The first argument provided from the associated hooks.

Tags
since
2.2.0
Return values
mixed$arg Returns the argument in case the webhook was hooked into a filter.

read_meta_data()

Read Meta Data from the database. Ignore any internal properties.

public read_meta_data([bool $force_read = false ]) : mixed

Uses it's own caches because get_metadata does not provide meta_ids.

Parameters
$force_read : bool = false

True to force a new DB read (and update cache).

Tags
since
2.6.0
Return values
mixed

set_api_version()

Set API version.

public set_api_version(int|string $version) : mixed
Parameters
$version : int|string

REST API version.

Tags
since
3.0.0
Return values
mixed

set_date_created()

Set webhook created date.

public set_date_created([string|int|null $date = null ]) : mixed
Parameters
$date : string|int|null = null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if their is no date.

Tags
since
3.2.0
Return values
mixed

set_date_modified()

Set webhook modified date.

public set_date_modified([string|int|null $date = null ]) : mixed
Parameters
$date : string|int|null = null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if their is no date.

Tags
since
3.2.0
Return values
mixed

set_delivery_url()

Set the delivery URL.

public set_delivery_url(string $url) : mixed
Parameters
$url : string

Delivery URL.

Tags
since
2.2.0
Return values
mixed

set_failure_count()

Set failure count.

public set_failure_count(bool $failure_count) : mixed
Parameters
$failure_count : bool

Total of failures.

Tags
since
3.2.0
Return values
mixed

set_meta_data()

Set all meta data from array.

public set_meta_data(array $data) : mixed
Parameters
$data : array

Key/Value pairs.

Tags
since
2.6.0
Return values
mixed

set_name()

Set webhook name.

public set_name(string $name) : mixed
Parameters
$name : string

Webhook name.

Tags
since
3.2.0
Return values
mixed

set_object_read()

Set object read property.

public set_object_read([bool $read = true ]) : mixed
Parameters
$read : bool = true

Should read?.

Tags
since
3.0.0
Return values
mixed

set_pending_delivery()

Set pending delivery.

public set_pending_delivery(bool $pending_delivery) : mixed
Parameters
$pending_delivery : bool

Set true if is pending for delivery.

Tags
since
3.2.0
Return values
mixed

set_props()

Set a collection of props in one go, collect any errors, and return the result.

public set_props(array $props[, string $context = 'set' ]) : bool|WP_Error

Only sets using public methods.

Parameters
$props : array

Key value pairs to set. Key is the prop and should map to a setter function name.

$context : string = 'set'

In what context to run this.

Tags
since
3.0.0
Return values
bool|WP_Error

set_secret()

Set the secret used for generating the HMAC-SHA256 signature.

public set_secret(string $secret) : mixed
Parameters
$secret : string

Secret.

Tags
since
2.2.0
Return values
mixed

set_status()

Set status.

public set_status(string $status) : mixed
Parameters
$status : string

Status.

Tags
since
3.2.0
Return values
mixed

set_topic()

Set the webhook topic and associated hooks.

public set_topic(string $topic) : mixed

The topic resource & event are also saved separately.

Parameters
$topic : string

Webhook topic.

Tags
since
2.2.0
Return values
mixed

set_user_id()

Set user ID.

public set_user_id(int $user_id) : mixed
Parameters
$user_id : int

User ID.

Tags
since
3.2.0
Return values
mixed

update_meta_data()

Update meta data by key or ID, if provided.

public update_meta_data(string $key, string|array $value, int $meta_id) : mixed
Parameters
$key : string

Meta key.

$value : string|array

Meta value.

$meta_id : int

Meta ID.

Tags
since
2.6.0
Return values
mixed

update_status()

Update the webhook status.

public update_status(string $status) : mixed
Parameters
$status : string

Status to set.

Tags
deprecated
3.2.0
since
2.2.0
Return values
mixed

error()

When invalid data is found, throw an exception unless reading from the DB.

protected error(string $code, string $message[, int $http_status_code = 400 ][, array $data = array() ]) : mixed
Parameters
$code : string

Error code.

$message : string

Error message.

$http_status_code : int = 400

HTTP status code.

$data : array = array()

Extra error data.

Tags
throws
WC_Data_Exception

Data Exception.

since
3.0.0
Return values
mixed

filter_null_meta()

Filter null meta values from array.

protected filter_null_meta(mixed $meta) : bool
Parameters
$meta : mixed

Meta value to check.

Tags
since
3.0.0
Return values
bool

get_prop()

Gets a prop for a getter method.

protected get_prop(string $prop[, string $context = 'view' ]) : mixed

Gets the value from either current pending changes, or the data itself. Context controls what happens to the value before it's returned.

Parameters
$prop : string

Name of prop to get.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
3.0.0
Return values
mixed

is_already_processed()

Checks if the specified resource has already been queued for delivery within the current request.

protected is_already_processed(mixed $arg) : bool

Helps avoid duplication of data being sent for topics that have more than one hook defined.

Parameters
$arg : mixed

First hook argument.

Return values
bool

is_internal_meta_key()

Check if the key is an internal one.

protected is_internal_meta_key(string $key) : bool
Parameters
$key : string

Key to check.

Tags
since
3.2.0
Return values
booltrue if it's an internal key, false otherwise

set_date_prop()

Sets a date prop whilst handling formatting and datetime objects.

protected set_date_prop(string $prop, string|int $value) : mixed
Parameters
$prop : string

Name of prop to set.

$value : string|int

Value of the prop.

Tags
since
3.0.0
Return values
mixed

set_prop()

Sets a prop for a setter method.

protected set_prop(string $prop, mixed $value) : mixed

This stores changes in a special array so we can track what needs saving the the DB later.

Parameters
$prop : string

Name of prop to set.

$value : mixed

Value of the prop.

Tags
since
3.0.0
Return values
mixed

failed_delivery()

Track consecutive delivery failures and automatically disable the webhook.

private failed_delivery() : mixed

if more than 5 consecutive failures occur. A failure is defined as a. non-2xx response.

Tags
since
2.2.0
Return values
mixed

get_legacy_api_payload()

Get Legacy API payload.

private get_legacy_api_payload(string $resource, int $resource_id, string $event) : array
Parameters
$resource : string

Resource type.

$resource_id : int

Resource ID.

$event : string

Event type.

Tags
since
3.0.0
Return values
array

get_topic_hooks()

Get the associated hook names for a topic.

private get_topic_hooks(string $topic) : array
Parameters
$topic : string

Topic name.

Tags
since
2.2.0
Return values
array

get_wp_api_payload()

Get WP API integration payload.

private get_wp_api_payload(string $resource, int $resource_id, string $event) : array
Parameters
$resource : string

Resource type.

$resource_id : int

Resource ID.

$event : string

Event type.

Tags
since
3.0.0
Return values
array

is_active()

Returns if webhook is active.

private is_active() : bool
Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_action()

Validates the criteria for certain actions.

private is_valid_action(mixed $arg) : bool
Parameters
$arg : mixed

First hook argument.

Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_post_action()

Validates post actions.

private is_valid_post_action(mixed $arg) : bool
Parameters
$arg : mixed

First hook argument.

Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_processing_action()

Validates WC processing actions.

private is_valid_processing_action(mixed $arg) : bool
Parameters
$arg : mixed

First hook argument.

Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_resource()

Checks the resource for this webhook is valid e.g. valid post status.

private is_valid_resource(mixed $arg) : bool
Parameters
$arg : mixed

First hook argument.

Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_topic()

Returns if topic is valid.

private is_valid_topic() : bool
Tags
since
3.6.0
Return values
boolTrue if validation passes.

is_valid_user_action()

Validates user actions.

private is_valid_user_action(mixed $arg) : bool
Parameters
$arg : mixed

First hook argument.

Tags
since
3.6.0
Return values
boolTrue if validation passes.

should_deliver()

Helper to check if the webhook should be delivered, as some hooks.

private should_deliver(mixed $arg) : bool

(like wp_trash_post) will fire for every post type, not just ours.

Parameters
$arg : mixed

First hook argument.

Tags
since
2.2.0
Return values
boolTrue if webhook should be delivered, false otherwise.