Medusa Webhook: The Best Tech Project of the Medusa Hackathon

Extensibility is one of the main features of Medusa, an open source headless ecommerce engine, and it has enabled developers to create plugins for Medusa. This infinitely increases the possibility of what can be done with Medusa.

Webhooks are web requests that are triggered on certain events. They allow applications to easily communicate with each other. Medusa has great potential for using webhooks to communicate with other services, so I decided to create the Medusa Webhook plugin for the Medusa Hackathon during Hacktoberfest 2022.

This webhook plugin allows you to add webhook triggers for order related events on your store. The possibilities that can be achieved are endless. This can be anything from sending a confirmation email to the customer to airdropping them to an NFT.

my experience working on this project

I was able to learn a lot about the inner workings of Medusa while working on this project. It turned out to be a great learning experience for me and an opportunity to do something for the community.

My experience creating plugins

Medusa has great documentation and guides for working with it. Although I had minor hiccups when creating the plugin, I was able to work my way up by seeing how the official plugins were implemented.

how i made the plugin

I started by following the Create a Plugin guide for Plugin. I followed the quickstart and set up dev environment guide to set up a local store to test my plugin. I also installed Medusa Admin and a NeXT.js storefront. When setting up the store, I also added --seed Flag, which added some dummy products to the store so that I don’t have to add the products manually. This process only took about 15 minutes.

I encountered a few hiccups during the development process and that’s when I got a glimpse at the implementation of the Notification Service Reference and the official plugins.

What does the webhook plugin do?

The plugin lets you set up webhook triggers on order events (orders being placed, canceled, updated, or fulfilled) in your store. For example, if you want to send an email to a customer when an order is successfully placed, you can set up an API route that sends an email to the customer.

The plugin will send a request to this API route with order and customer data that can be used by your code to determine what should be included in the message.

You can also pass in a header to go with the request. This is useful when you need to send a secret key for authentication. The default webhook URL and header can also be overridden depending on the event.

The plugin service also exposes a postWebhook Method that can be used to trigger a webhook from your custom code in the Medusa Store.

using a plugin

Before trying to use the plugin, here are a few things you should have.


Installing and setting up the Webhooks plugin

To install the plugin using npm, run the following command in your Medusa Server directory:

npm install medusa-plugin-webhooks
enter fullscreen mode

exit fullscreen mode

If you prefer to use Yarn, run the following command in your Medusa Server directory:

yarn add medusa-plugin-webhooks
enter fullscreen mode

exit fullscreen mode

Once the plugin is installed, we need to add it plugins array in medusa-config.js File in your Medusa Server directory:

const plugins = [
    resolve: "medusa-plugin-webhooks",
    options: {
      webhook_headers: {
        "x-api-key": "supersecretapikey", // OPTIONAL: You can add custom headers (for example, for authentication)
      webhook_config: {
        "order.placed": {
          enabled: true,
          overrideUrl: "<>", // OPTIONAL: You can override the URL on a per-event basis,
          overrideHeaders: {
            "x-api-key": "supersecretorderplacedapikey", // OPTIONAL: You can override the headers on a per-event basis
enter fullscreen mode

exit fullscreen mode

Currently, these four (4) events are supported:

  • order.placed
  • order.updated
  • order.completed
  • order.canceled

By default, notifications are disabled for all events. To enable notifications for any of the above events, set enabled property to true In webhook_config object (see example configuration above).

You can override the URL or header for any of the above events by setting overrideUrl either overrideHeaders properties in webhook_config object (see example configuration above).

Triggering a webhook request from your custom code

You can trigger the webhook request from your code by resolving the webhook service and then using postWebhook Celebration. For example:

const webhooksService = scope.resolve("webhooksService");
await webhooksService.postWebhook(
    event: "order.placed",
    data: {
      order_id: "order_id",
      customer_id: "customer_id",
      total_price: 1000,
      currency_code: "USD",
  "", // OPTIONAL: You can pass in an URL override here as well
    "x-api-key": "customeventsapikey", // OPTIONAL: You can pass in custom headers here as well
enter fullscreen mode

exit fullscreen mode


Installing this plugin is a quick and easy task. If you have a problem, feel free to open an issue on GitHub.

If you have any issue or query related to Medusa, feel free to contact Medusa team via Discord.

Leave a Comment