Webhook
Overviewβ
Webhook is the configuration that allows sending the API request to another server with entities based on the event of Magento when some events occur. Thanks to the Mageplaza Webhook extension, it will auto-activate an error email notification during the sending of the Hook to the customers when your store has some events such as New Order, New Order Comment, New Invoice, New Customer, New Product, Subscribe, etc. The module especially allows data to be sent automatically every minute, daily, weekly, and monthly. All will be done quickly and conveniently with the help of this great module. Let's follow us to explore this plugin!
New in Webhook 4.5.0β
- Synchronous and queued delivery, with order-status filters for order hooks.
- Connector templates, Bearer Token/API Key authentication, and Send Test.
- HMAC request signing and replay protection.
- Delivery timeout, Smart Retry, and failure alerts.
- Blocking validation for storefront actions.
- Delivery analytics and replay by date range.
- GraphQL hook management and order status.
Outstanding Featuresβ
| Outstanding features | Description | |
|---|---|---|
| 1 | Secure and instant Data Transmission | Customizable Event Triggers: Send an API request to a configurable destination (URL) when specific events occur by specific events related to orders, invoices, shipments, credit memos, customer accounts, products, categories, and carts such as order creation, customer registration, product updates, etc. Flexible Conditions and Actions: Basically, user-defined HTTP callbacks that are triggered by specific events. |
| 2 | Marketing Enhancement | Multiple System Compatibility: Facilitates communication with various external systems such as CRMs, ERP systems, and other third-party services. The new data, such as new order/new customers or any related updates, will be sent automatically to these servers. The united and updated important data lead the sales and the after-sales process will progress smoothly and effectively accordingly. |
| 3 | Automation and Workflow Efficiency | Clean log automatically: Allow admins to set the system to clean logs automatically. Admins can set up the number of logs, and the system will automatically remove the older logs, keeping only the newest ones. Store owners can also deactivate this feature. Automatic Error hook replay: The module enables the system to automatically replay the hook with βErrorβ status after an amount of time set by admins. The system can auto-resend a new API request after fixing its errors, saving the user's time and effort in checking and replaying hooks manually whenever errors arise. Better hook log management: Help admins update the status of hooks: success or error. There is a grid to show the hook details, including Log ID, name, entity, and, especially, preview the response quickly from the action field of the log for a quicker view. Webhook alert: Store owners are able to configure automatic notification emails about errors during sending API requests. Additionally, admins can also provide the email address(es) to which they want the system to send notifications. |
Installation Guideβ
We offer two methods for installing our plugins: the Copy & Paste method and the Composer method. Please follow the detailed instructions provided below.
Method 1: Installation via Copy & Pasteβ
To install our plugins using the Copy & Paste method, kindly follow the instructions at the link below:
How to Install Magento 2 Extension via Copy & Paste
Method 2: Installation via Composerβ
Composer name: mageplaza/module-webhook
To install our extensions using Composer, please refer to the comprehensive guide at the link below:
How to Install Magento Extension via Composer
By following these guides, you can ensure that the installation process is handled correctly, allowing you to fully utilize the features and benefits of our plugins.
Module Update Guideβ
Keeping your module updated ensures optimal performance. Follow one of these steps to update your module:
- By Account Dashboard: Log in to your Mageplaza account > go to the My Licenses section > click on the Download button > choose the latest version from the popup.
- By composer: Kindly use the following commands to update module via composer
composer require mageplaza/module-webhook
php bin/magento setup:upgrade
php bin/magento setup:di:compile
Updating a module by Composer ensures efficient dependency management, version control, and integration with development tools, making the process faster and more reliable.
Guide to install the libraryββ
Please run the below command to install the module library if you install the module via composer:
composer require liquid/liquid
How to configureβ
I. Configurationβ
Login to the Magento Admin, choose Store > Settings > Configuration > Mageplaza Extensions > Webhook.

1. Generalβ
- Enable: Choose "Yes" to enable this module or "No" to disable it.
- Abandoned Cart After: Set the hours for Abandoned Cart. We recommend the period time as 1, 6, 10, 12, 24.
- Keep Logs: Enter the number of keep logs. It will auto-delete the logs if it reaches the selected number and keeps the number of selected logs. It will make the logs clear everyday.
- Alert on Error: Choose "Yes" to send the notification when sending an email. To avoid sending the email to the spam box, you should install SMTP extension

2. Schedule For Cronβ
Normally, the hook will be sent immediately after an event, such as creating an order, changing a product, etc., is completed. When setting up Cron, these hooks will not be sent immediately but will be scheduled to a fixed period of time when the hooks are scheduled to be sent. This has the effect that the client can control the time it takes to receive data from the hook and avoid reducing the performance of the above events because when the hook is sent right after creating the event, it will increase the load time to complete, leading reduced performance

- Schedule For Cron: Select the time to synchronize send data:
- Disable: will send the data right after the event occurs. For example: Create Hook with New order, after each new order, the data will be synchronized to the app. You can see the list that has been submitted at Logs.
- Every Minute: data will be synchronized every minute.
- Daily: data is synchronized every day.
- Weekly: data will be synchronized on Monday every week
- Monthly: data will be synchronized every month on the first day of each month.
- Start Time: Only show this field when selecting Daily/ Weekly/ Monthly. Choose the time to synchronize data. For example: Schedule For Cron is Daily, Start Time is 2:30:00, every day at 2:30:00 data will be synchronized
- Note: If the logs report an Error on time period synchronized, the system will send an email notification to admin.
II. Manage Hookβ
1. Gridβ
The Grid shows the hook details, including Log ID, name, and entity, and, especially, previews the status quickly from the action field of the log for a quicker view. With this function, admins can easily check if hooks are enabled or disabled.
From the Admin Panel, go to System > Webhook > Manage Hooks.

- This section records created Webhooks with basic information as Name, Status, Store View, Entity, Created Date and Update date, etc
- Admins can perform some actions:
Delete: Choose Webhooks that you want to deleteChange Status: Tick to choose the Webhook that you want to change the status, choose "Enable" to use WebhookEdit: Click "Edit" to edit the content of Webhook.
- Also, admins can filter, change the Store View, hide/show columns on Grid.
- For
Add Newbutton, you can chooseTriggertype toCreate New Hookand activate the data to the server. Especially, Event Subscribe is also supported.

2. Create a Hookβ
A hook helps store owners can trigger specific actions or API requests when predefined events occur in the system. They are used to integrate Magento with external systems and automate workflows.
How to Create New Hookβ
From the Admin Panel, go to System > Webhook > Manage Hooks, click the arrow next to the Add New button in the right corner and choose a hook type such as Order, New Product, Update Product, Delete Product, etc.

2.1. Generalβ

- Delivery Mode: Choose Synchronous (default) to send the webhook during the event request, or Asynchronous (Queue) to queue delivery so the event request does not wait for the endpoint. Asynchronous delivery requires a running Magento message queue consumer.
- Order Status: For order hooks, select which order statuses trigger the hook.

- Name: Enter the name of the Hook. This name will display when sending the email to customers
- Status: Choose "Enable" to use Hook
- Store View: Choose Store View that Hook is displayed. With unselected Store View, Hook will not appear.
- Priority:
- Enter the priority for Hook
- The smaller the Hook priority, the higher its priority. O is the highest priority.
2.2. Actionsβ

Payload URL:
- You need to insert a URL, and the Magento site will send the request to that URL.
- This is a field that is not allowed to be empty. If you leave it blank, it will show "This is a required field".
- Also, you can insert some variables at the end of the URL. For example: https://webhook-test.com/7929a5516ecf665d940f62837b143a5a/4000831345, etc or https://webhook-test.com/7929a5516ecf665d940f62837b143a5a/4000831345 new shipment = {insert variable} with the domain is your API account name.
Method: Choose the HTTP method for the request. The default is
POST.- GET: Get the data from the server
- POST: Create a new object
- PUT: Update an object
- DELETE: Delete an object
- HEAD: The same as GET, but it doesn't require the
Bodysection - CONNECT: Converts the requested connection into a transparent TCP/IP tunnel, usually to facilitate SSL encryption (HTTPS) communication through an unencrypted HTTP proxy.
- OPTIONS: Describe the options. An OPTIONS request should return data describing other methods and operations on the server that support certain URLs.
- TRACE: Repeats the request so that the customers can see any changes or additions (if so) that have been made by the intermediate server.
- PATCH: Apply a modified part to an object.
Authentication: Choose Basic, Digest, Bearer Token, API Key, or None. Bearer tokens and API keys are stored encrypted. For API Key authentication, set the header name expected by the receiving service.
Connector: Choose an available service format to load a compatible request body template. The current connectors include Slack, Discord, Telegram, Google Sheets, Google Chat, Microsoft Teams, Zapier, Make, n8n, and Generic Webhook. Select a connector, then click Load Template; review the generated body and fill in the service's required URL and fields.


Basic: Enter the receiving service's username and password.
Digest: Enter the digest authentication values required by the receiving service.
Bearer Token: Enter the token; Webhook sends it as a Bearer authorization value.
API Key: Enter the key and the header name expected by the receiving service. The default header name is
X-API-Key.None: Send the request without authentication.

Headers: Click the
Addbutton to add the values of headers, such asName and Value, as required by the server to be able to call that API. For example: Name: Authorization, Value isToken token = "Your API Key"Content-type: Select the content type to send the information. For Method as
GET, you can leave this field blank.
Body: For methods such as POST or PUT, enter the request content here. Click Insert Variable to add event data. To start with a service-compatible body, choose a connector and click Load Template.

- You may see the list of variables in the body by clicking on the 'Preview' button. This action will display a comprehensive overview of the variables.

2.3. HMAC Signingβ
Turn on Enable HMAC Signing to attach a signature to each outgoing request. Choose SHA-256, SHA-1, or SHA-512, set the signing secret and signature header, and enable Replay Protection to include a timestamp in the signed value. The receiving service must verify the signature using the same secret and algorithm.

Signing Secret: Enter a shared secret or click Regenerate. The saved value is masked; use Show or Copy when needed.
Signature Header: Header name that carries the signature. Default:
X-Mageplaza-Webhook-Signature.Replay Protection: Adds a timestamp so the receiving service can reject old requests.
Click Send Test in the hook form to send a sample request to the configured endpoint and review its response before relying on the hook. The test uses sample order data; it does not create a Magento order.
To test an endpoint separately, you can also use https://webhook-test.com/. This test hook only works with the POST method.
You can also change the payloadUrl of the hook like https://webhook-test.com/7929a5516ecf665d940f62837b143a5a
After the hook runs, let's check:

3. Logsβ
The log in each hook can only view the hook's list of logs. Users can track and monitor each webhook event and debug and troubleshoot issues. The log in each hook list shows the entire log of that hook so the user can check whether the hook was sent successfully or not. This allows admins to check the message to facilitate debugging.
Here are the change logs for the synchronization process of each hook.

III. Logsβ
Logs record webhook deliveries, including their status, entity, and message. Open a log to review its request body and endpoint response. Use Replay on a log to send that delivery again. With Smart Retry enabled, delivery statuses also show Pending Retry or Dead while retries are scheduled or exhausted.
From the Admin Panel, go to System > Webhook > Logs
This section will record all the Webhooks change logs, such as name, status, entity, message, etc. When you click on any file, it will auto-open that file.

View Logβ
Click View; it will redirect the email receiver to the Logs page in order to view the detailed logs.

IV. Delivery Controlsβ
Open Stores > Configuration > Mageplaza Extensions > Webhook to configure delivery controls.
1. Delivery Timeoutβ
In the General group, scroll past Keep logs to Delivery Timeout (ms). This setting limits how long a synchronous webhook waits for its endpoint. Default: 5000 milliseconds.

2. Retry (Smart Retry)β
Enable Smart Retry to retry failed deliveries. Configure the maximum number of retries, the initial backoff delay, and the maximum backoff delay. When retries are exhausted, the delivery is marked Dead. Defaults: 5 retries, 60-second base delay, and 3600-second cap. Retry processing requires Magento cron to run.

| Field | Type | Description |
|---|---|---|
| Enable Smart Retry | Yes/No | Turn automatic retries on or off. |
| Max Retries | Number | Maximum retry attempts for a failed delivery. |
| Backoff Base (seconds) | Number | Starting delay used by the retry backoff. |
| Backoff Cap (seconds) | Number | Maximum delay used by the retry backoff. |
3. Failure Alertingβ
Threshold alerts notify the configured recipients after a hook reaches the consecutive failure limit. You can also choose to disable a hook after repeated failures. The alert email includes the reason for the failure and a View Logs link. Threshold alerts are off by default; the default threshold is 10 failures.

| Field | Type | Description |
|---|---|---|
| Enable Threshold Alert | Yes/No | Turn consecutive-failure alerts on or off. |
| Alert Email Recipient(s) | Email addresses | Recipients separated by commas. |
| Consecutive Failure Threshold | Number | Consecutive failures required before sending an alert. Default: 10. |
| Auto-disable Hook on Repeated Failure | Yes/No | Disable the hook after the alert threshold is reached. Off by default. |
The alert email shows the failure reason, the store, and a View Logs button that opens the Webhook logs.

4. Synchronous Validationβ
Enable synchronous validation in the Webhook configuration, then edit a hook and open its Validation tab. Set Blocking Validation Hook to Yes, choose a validation event, and configure its timeout and fail mode. A blocking hook runs in the checkout request and can prevent the action from completing; use a trusted, tested endpoint. This option is off by default.

| Field | Type | Description |
|---|---|---|
| Enable Synchronous Validation | Yes/No | Turn blocking validation hooks on or off. Off by default. |
| Default Timeout (ms) | Number | How long to wait for a blocking validation endpoint before applying the fail mode. Default: 2000. |
| Default Fail Mode | Dropdown | What to do when a blocking endpoint times out or errors. Fail open (recommended) never stops a sale. |
Open the hook's Validation tab and enable Blocking Validation Hook for the event you want the endpoint to validate.

For a blocking hook, Fail open allows the action if the validation endpoint times out or errors. Fail closed blocks the action in that case. The store-level timeout and fail mode are defaults; a hook can override them.
V. Webhook Dashboardβ
Go to System > Webhook > Dashboard. Choose a date range and click Apply to review delivery totals, success rate, errors, dead deliveries, and average and 95th-percentile response times. The charts show delivery volume over time and the breakdown by hook. Use Replay failed in range to queue failed deliveries from the selected period for replay. If the selected range contains no deliveries, the totals show zero and the charts have no data.

VI. GraphQL APIβ
Webhook v4.5.0 adds GraphQL operations to list, fetch, create, update, and delete webhook definitions. The Hook response includes order_status for order hooks. These operations require an admin authorization context with the Manage Hooks permission.
Available operations:
- Queries:
mpWebhookHooks,mpWebhookHook - Mutations:
createMpWebhookHook,updateMpWebhookHook,deleteMpWebhookHook
The API exposes hook configuration fields such as name, status, hook_type, payload_url, method, content_type, priority, and order_status. It does not expose stored credentials or signing secrets.
FAQsβ
Support and Assistanceβ
1. Customer Supportβ
For any assistance, please visit our Support page or email us at cs@mageplaza.com/ sales@mageplaza.com
2. Create a Ticketβ
If you need to create a support ticket, please use the following link:
Operating Hoursβ
Our support team is available during the following hours:
- Monday to Friday: 8:00 AM - 23:59 PM
- Saturday: 8:00 AM - 12:00 PM
- Sunday: Closed
Refund Policyβ
We understand that sometimes things don't go as planned. Please review our refund policy for detailed information:
Frequently Asked Questions (FAQ)β
For quick answers to common questions, please visit our FAQ page: