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

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

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

My Experience Working on This Project

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

My Experience Creating the Plugin

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 out by looking at how the official plugins were implemented.

How I Created the Plugin

I started out by following the Create a Plugin guide for the plugin. I followed the Quickstart and Set Up Dev Environment guides to set up a local store for me to test my plugin. I also set up Medusa Admin and a Next.js storefront. While setting up the store, I also added the --seed flag, which added some dummy products to the store so that I didn’t have to add products manually. This process took only approximately 15 minutes.

I encountered some hiccups during the development process and that is when the Notifications Service Reference and a sneak peek at the implementations of the official plugins came in handy.

What Does the Webhook Plugin do?

The plugin lets you set up webhook triggers on order events (order being placed, cancelled, updated, or completed) in your store. For example, if you would like to send an email to the customer when they place an order successfully, you could set up an api route which sends out the email to the customer.

The plugin will send a request to this API route along with the order and customer data which can be used by your code in determining whom to send the email to along with what the message should contain.

You can also pass in headers to go along with the request. This is useful when you have to send a secret key for authentication. The default webhook URL and headers can also be overridden on an event basis.

The plugin service also exposes a postWebhook method that can be used to trigger webhooks from your custom code in the Medusa store.

Using the Plugin

Before trying to use the plugin, here are some things you must have.

Prerequisites

A Medusa server (Quickstart Guide)
Redis setup on your Medusa server (Configuring Redis on your Medusa server)
A webhook endpoint to which you can post webhooks (for testing purposes, I recommend using Svix Play)

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

If you prefer using Yarn, run the following command in your Medusa server directory:

yarn add medusa-plugin-webhooks

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

const plugins = [
  ...{
    resolve: "medusa-plugin-webhooks",
    options: {
      webhook_url: "https://mystore.com/events", // REQUIRED: CHANGE THIS TO A VALID WEBHOOK ENDPOINT
      webhook_headers: {
        "x-api-key": "supersecretapikey", // OPTIONAL: You can add custom headers (for example, for authentication)
      },
      webhook_config: {
        "order.placed": {
          enabled: true,
          overrideUrl: "<https://mystore.com/events/order-placed>", // 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
          },
        },
      },
    },
  },
];

Currently, these four (4) events are supported:

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

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

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

Triggering a Webhook Request from Your Custom Code

You can trigger a webhook request from your code by resolving the webhook service and then using the postWebhook function. 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",
    },
  },
  "mystore.com/events/custom", // 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
  }
);

Conclusion

Setting up this plugin is a quick and easy task. If you have any issues, feel free to open an issue on GitHub.

NPM Package - medusa-plugin-webhooks
GitHub Repository - AnishDe12020/medusa-plugin-webhooks

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.

Medusa Webhooks: The Best Technical Project of the Medusa Hackathon