# Webhooks #
The webhooks API allows you to create, view, update, and delete individual, or a batch, of webhooks.
Webhooks can be managed via the WooCommerce settings screen or by using the REST API endpoints. The `WC_Webhook` class manages all data storage and retrieval of the webhook custom post type, as well as enqueuing webhook actions and processing/delivering/logging webhooks. On `woocommerce_init`, active webhooks are loaded.
Each webhook has:
* `status`: active (delivers payload), paused (delivery paused by admin), disabled (delivery paused by failure).
* `topic`: determines which resource events the webhook is triggered for.
* `delivery URL`: URL where the payload is delivered, must be HTTP or HTTPS.
* `secret`: an optional secret key that is used to generate a HMAC-SHA256 hash of the request body so the receiver can verify authenticity of the webhook.
* `hooks`: an array of hook names that are added and bound to the webhook for processing.
### Topics ###
The topic is a combination resource (e.g. order) and event (e.g. created) and maps to one or more hook names (e.g. `woocommerce_checkout_order_processed`). Webhooks can be created using the topic name and the appropriate hooks are automatically added.
Core topics are:
* Coupons: `coupon.created`, `coupon.updated` and `coupon.deleted`.
* Customers: `customer.created`, `customer.updated` and `customer.deleted`.
* Orders: `order.created`, `order.updated` and `order.deleted`.
* Products: `product.created`, `product.updated` and `product.deleted`.
Custom topics can also be used which map to a single hook name, for example you could add a webhook with topic `action.woocommerce_add_to_cart` that is triggered on that event. Custom topics pass the first hook argument to the payload, so in this example the `cart_item_key` would be included in the payload.
### Delivery/payload ###
Delivery is performed using `wp_remote_post()` (HTTP POST) and processed in the background by default using wp-cron. A few custom headers are added to the request to help the receiver process the webhook:
* `X-WC-Webhook-Source`: `http://example.com/`.
* `X-WC-Webhook-Topic` - e.g. `order.updated`.
* `X-WC-Webhook-Resource` - e.g. `order`.
* `X-WC-Webhook-Event` - e.g. `updated`.
* `X-WC-Webhook-Signature` - a base64 encoded HMAC-SHA256 hash of the payload.
* `X-WC-Webhook-ID` - webhook's post ID.
* `X-WC-Webhook-Delivery-ID` - delivery log ID (a comment).
The payload is JSON encoded and for API resources (coupons, customers, orders, products), the response is exactly the same as if requested via the REST API.
### Logging ###
Requests/responses are logged using the WooCommerce logging system. Each delivery log includes:
* Request duration.
* Request URL, method, headers, and body.
* Response Code, message, headers, and body.
After 5 consecutive failed deliveries (as defined by a non HTTP 2xx response code), the webhook is disabled and must be edited via the REST API to re-enable.
Delivery logs can be accessed in "WooCommerce" > "Status" > "Logs".
### Visual interface ###
You can find the Webhooks interface going to "WooCommerce" > "Settings" > "Advanced" > "Webhooks", see our [Visual Webhooks docs](https://docs.woocommerce.com/document/webhooks/) for more details.
## Webhook properties ##
| 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-onlymandatory |
| `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|username if not provided. write-onlymandatory |
| `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 |
## Create a webhook ##
This API helps you to create a new webhook.
### HTTP request ###