Skip to main content

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​

Outstanding Features​

Outstanding featuresDescription
1Secure 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.

2Marketing EnhancementMultiple 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.
3Automation 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:

  1. 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.
  2. 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 delete
    • Change Status: Tick to choose the Webhook that you want to change the status, choose "Enable" to use Webhook
    • Edit: Click "Edit" to edit the content of Webhook.
  • Also, admins can filter, change the Store View, hide/show columns on Grid.
  • For Add New button, you can choose Trigger type to Create New Hook and 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:

  • 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 Body section
    • 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 Add button to add the values of headers, such as Name and Value, as required by the server to be able to call that API. For example: Name: Authorization, Value is Token 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.

FieldTypeDescription
Enable Smart RetryYes/NoTurn automatic retries on or off.
Max RetriesNumberMaximum retry attempts for a failed delivery.
Backoff Base (seconds)NumberStarting delay used by the retry backoff.
Backoff Cap (seconds)NumberMaximum 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.

FieldTypeDescription
Enable Threshold AlertYes/NoTurn consecutive-failure alerts on or off.
Alert Email Recipient(s)Email addressesRecipients separated by commas.
Consecutive Failure ThresholdNumberConsecutive failures required before sending an alert. Default: 10.
Auto-disable Hook on Repeated FailureYes/NoDisable 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.

FieldTypeDescription
Enable Synchronous ValidationYes/NoTurn blocking validation hooks on or off. Off by default.
Default Timeout (ms)NumberHow long to wait for a blocking validation endpoint before applying the fail mode. Default: 2000.
Default Fail ModeDropdownWhat 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​

I used the CRM system. Can I config this module to send instantly updated data to this system when customers make new orders?
Yes, absolutely. Please select the hook trigger entity as a new order and insert your payload URL of the CRM system from the admin backend.
Can I set a time to define an abandoned cart?
Yes, it can be done easily by adding time by minutes in the admin backend.
How many logs can be kept?
It is not limited. You can freely set the number from the backend. When the total of logs reaches a specific number, the system will automatically process cleaning logs.
When the request from a hook fails, how can I know?
How can I prevent the alert email from being sent to the spam box?
To prevent this issue, you can take a look at Magento 2 SMTP, which can meet your expectations.

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:

Create Ticket 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:

Refund Policy Link

Frequently Asked Questions (FAQ)​

For quick answers to common questions, please visit our FAQ page:

FAQ Page Link