WooCommerce REST API 文档

title: "Webhooks #" post_status: publish comment_status: open taxonomy: category: - woocommerce-rest-api post_tag: - Wp Api V3 - Includes - Source

Webhooks

Webhooks API 允许您创建、查看、更新和删除单个或批量 Webhook。

Webhook 可以通过 WooCommerce 设置界面或使用 REST API 端点进行管理。WC_Webhook 类负责管理 Webhook 自定义文章类型的所有数据存储和检索，以及将 Webhook 操作加入队列并处理/发送/记录 Webhook。在 woocommerce_init 时，会加载所有活跃的 Webhook。

每个 Webhook 包含：

主题

主题是资源（例如订单）和事件（例如创建）的组合，并映射到一个或多个钩子名称（例如 woocommerce_checkout_order_processed）。可以使用主题名称创建 Webhook，相应的钩子会自动添加。

核心主题包括：

也可以使用自定义主题，它们映射到单个钩子名称。例如，您可以添加一个主题为 action.woocommerce_add_to_cart 的 Webhook，该 Webhook 会在该事件触发时执行。自定义主题会将第一个钩子参数传递给有效载荷，因此在此示例中，cart_item_key 将包含在有效载荷中。

交付/负载

交付默认使用 wp_remote_post()（HTTP POST）执行，并通过 wp-cron 在后台处理。请求中添加了一些自定义标头，以帮助接收方处理 Webhook：

负载采用 JSON 编码，对于 API 资源（优惠券、客户、订单、产品），其响应与通过 REST API 请求时完全相同。

日志记录

请求/响应使用 WooCommerce 日志系统进行记录。每条投递日志包含：

连续 5 次投递失败（由非 HTTP 2xx 响应代码定义）后，Webhook 将被禁用，必须通过 REST API 编辑以重新启用。

投递日志可在 "WooCommerce" > "状态" > "日志" 中访问。

可视化界面

您可以通过访问“WooCommerce”>“设置”>“高级”>“Webhooks”找到 Webhooks 界面，更多详情请参阅我们的可视化 Webhooks 文档。

Webhook 属性

Attribute Type Description
id integer Unique identifier for the resource. read-only
name string A friendly name for the webhook.
status string Webhook status. Options: active, paused and disabled. Default is active.
topic string Webhook topic. mandatory
resource string Webhook resource. read-only
event string Webhook event. read-only
hooks array WooCommerce action names associated with the webhook. read-only
delivery_url string The URL where the webhook payload is delivered. read-only mandatory
secret string Secret key used to generate a hash of the delivered webhook and provided in the request headers. This will default is a MD5 hash from the current user's ID
date_created date-time The date the webhook was created, in the site's timezone. read-only
date_created_gmt date-time The date the webhook was created, as GMT. read-only
date_modified date-time The date the webhook was last modified, in the site's timezone. read-only
date_modified_gmt date-time The date the webhook was last modified, as GMT. read-only

创建 Webhook

此 API 可帮助您创建一个新的 Webhook。

HTTP 请求

POST
/wp-json/wc/v3/webhooks
curl -X POST https://example.com/wp-json/wc/v3/webhooks \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Order updated",
  "topic": "order.updated",
  "delivery_url": "http://requestb.in/1g0sxmo1"
}'

const data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
};

WooCommerce.post("webhooks", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php
$data = [
    'name' => 'Order updated',
    'topic' => 'order.updated',
    'delivery_url' => 'http://requestb.in/1g0sxmo1'
];

print_r($woocommerce->post('webhooks', $data));
?>

data = {
    "name": "Order updated",
    "topic": "order.updated",
    "delivery_url": "http://requestb.in/1g0sxmo1"
}

print(wcapi.post("webhooks", data).json())

data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
}

woocommerce.post("webhooks", data).parsed_response

JSON 响应示例：

{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:17:52",
  "date_modified_gmt": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks"
      }
    ]
  }
}

Retrieve a webhook

This API lets you retrieve and view a specific webhook.

HTTP request

GET
/wp-json/wc/v3/webhooks/<id>
curl https://example.com/wp-json/wc/v3/webhooks/142 \
    -u consumer_key:consumer_secret

WooCommerce.get("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php print_r($woocommerce->get('webhooks/142')); ?>

print(wcapi.get("webhooks/142").json())

woocommerce.get("webhooks/142").parsed_response

JSON response example:

{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:17:52",
  "date_modified_gmt": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks"
      }
    ]
  }
}

List all webhooks

This API helps you to view all the webhooks.

HTTP request

GET
/wp-json/wc/v3/webhooks
curl https://example.com/wp-json/wc/v3/webhooks \
    -u consumer_key:consumer_secret

WooCommerce.get("webhooks")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php print_r($woocommerce->get('webhooks')); ?>

print(wcapi.get("webhooks").json())

woocommerce.get("webhooks").parsed_response

JSON response example:

[
  {
    "id": 143,
    "name": "Customer created",
    "status": "active",
    "topic": "customer.created",
    "resource": "customer",
    "event": "created",
    "hooks": [
      "user_register",
      "woocommerce_created_customer",
      "woocommerce_api_create_customer"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T23:17:52",
    "date_created_gmt": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T23:17:52",
    "date_modified_gmt": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v3/webhooks/143"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v3/webhooks"
        }
      ]
    }
  },
  {
    "id": 142,
    "name": "Order updated",
    "status": "active",
    "topic": "order.updated",
    "resource": "order",
    "event": "updated",
    "hooks": [
      "woocommerce_process_shop_order_meta",
      "woocommerce_api_edit_order",
      "woocommerce_order_edit_status",
      "woocommerce_order_status_changed"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T23:17:52",
    "date_created_gmt": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T23:17:52",
    "date_modified_gmt": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v3/webhooks/142"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v3/webhooks"
        }
      ]
    }
  }
]

Available parameters

Parameter Type Description
context string Scope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
page integer Current page of the collection. Default is 1.
per_page integer Maximum number of items to be returned in result set. Default is 10.
search string Limit results to those matching a string.
after string Limit response to resources published after a given ISO8601 compliant date.
before string Limit response to resources published before a given ISO8601 compliant date.
dates_are_gmt boolean Whether to interpret dates as GMT dates when limiting response by published date.
exclude array Ensure result set excludes specific IDs.
include array Limit result set to specific ids.
offset integer Offset the result set by a specific number of items.
order string Order sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderby string Sort collection by object attribute. Options: date, id, include, title and slug. Default is date.
status string Limit result set to webhooks assigned a specific status. Options: all, active, paused and disabled. Default is all.

Update a webhook

This API lets you make changes to a webhook.

HTTP request

PUT
/wp-json/wc/v3/webhooks/<id>
curl -X PUT https://example.com/wp-json/wc/v3/webhooks/142 \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "status": "paused"
}'

const data = {
  status: "paused"
}

WooCommerce.put("webhooks/142", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php
$data = [
    'status' => 'paused'
];

print_r($woocommerce->put('webhooks/142', $data));
?>

data = {
    "status": "paused"
}

print(wcapi.put("webhooks/142", data).json())

data = {
  status: "paused"
}

woocommerce.put("webhooks/142", data).parsed_response

JSON response example:

{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T17:30:12",
  "date_modified_gmt": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks"
      }
    ]
  }
}

Delete a webhook

This API helps you delete a webhook.

HTTP request

DELETE
/wp-json/wc/v3/webhooks/<id>
curl -X DELETE https://example.com/wp-json/wc/v3/webhooks/142 \
    -u consumer_key:consumer_secret

WooCommerce.delete("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php print_r($woocommerce->delete('webhooks/142')); ?>

print(wcapi.delete("webhooks/142").json())

woocommerce.delete("webhooks/142").parsed_response

JSON response example:

{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:30:12",
  "date_modified_gmt": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/webhooks"
      }
    ]
  }
}

Available parameters

Parameter Type Description
force string Use true whether to permanently delete the webhook, Defaults is false.

批量更新 Webhook

此 API 可帮助您批量创建、更新和删除多个 Webhook。

HTTP request

POST
/wp-json/wc/v3/webhooks/batch
curl -X POST https://example.com//wp-json/wc/v3/webhooks/batch \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "create": [
    {
      "name": "Coupon created",
      "topic": "coupon.created",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    },
    {
      "name": "Customer deleted",
      "topic": "customer.deleted",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    }
  ],
  "delete": [
    143
  ]
}'

const data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
};

WooCommerce.post("webhooks/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe',
            'topic' => 'coupon.created',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ],
        [
            'name' => 'Customer deleted',
            'topic' => 'customer.deleted',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ]
    ],
    'delete' => [
        143
    ]
];

print_r($woocommerce->post('webhooks/batch', $data));
?>

data = {
    "create": [
        {
            "name": "Round toe",
            "topic": "coupon.created",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        },
        {
            "name": "Customer deleted",
            "topic": "customer.deleted",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        }
    ],
    "delete": [
        143
    ]
}

print(wcapi.post("webhooks/batch", data).json())

data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
}

woocommerce.post("webhooks/batch", data).parsed_response

JSON response example:

{
  "create": [
    {
      "id": 146,
      "name": "Coupon created",
      "status": "active",
      "topic": "coupon.created",
      "resource": "coupon",
      "event": "created",
      "hooks": [
        "woocommerce_process_shop_coupon_meta",
        "woocommerce_api_create_coupon"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-25T01:56:26",
      "date_created_gmt": "2016-05-24T22:56:26",
      "date_modified": "2016-05-25T01:56:26",
      "date_modified_gmt": "2016-05-24T22:56:26",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks/146"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks"
          }
        ]
      }
    },
    {
      "id": 147,
      "name": "Customer deleted",
      "status": "active",
      "topic": "customer.deleted",
      "resource": "customer",
      "event": "deleted",
      "hooks": [
        "delete_user"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-25T01:56:30",
      "date_created_gmt": "2016-05-24T22:56:30",
      "date_modified": "2016-05-25T01:56:30",
      "date_modified_gmt": "2016-05-24T22:56:30",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks/147"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 143,
      "name": "Webhook created on May 24, 2016 @ 03:20 AM",
      "status": "active",
      "topic": "customer.created",
      "resource": "customer",
      "event": "created",
      "hooks": [
        "user_register",
        "woocommerce_created_customer",
        "woocommerce_api_create_customer"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-15T23:17:52",
      "date_created_gmt": "2016-05-15T20:17:52",
      "date_modified": "2016-05-15T23:17:52",
      "date_modified_gmt": "2016-05-15T20:17:52",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks/143"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v3/webhooks"
          }
        ]
      }
    }
  ]
}