Medusa Webhooks: The Best Technical Project of the Medusa Hackathon
Tags: opensource, javascript, webdev, devjournal
Published: 2022-11-10 11:57:55

Extensibility is one of the core features of [Medusa](https://medusajs.com/), 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](https://github.com/AnishDe12020/medusa-plugin-webhooks) for the [Medusa Hackathon during Hacktoberfest 2022](https://medusajs.com/blog/medusa-hackathon).

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](https://docs.medusajs.com/advanced/backend/plugins/create) for the plugin. I followed the [Quickstart](https://docs.medusajs.com/quickstart/quick-start) and [Set Up Dev Environment](https://docs.medusajs.com/tutorial/set-up-your-development-environment) guides to set up a local store for me to test my plugin. I also set up [Medusa Admin](https://docs.medusajs.com/admin/quickstart) and a [Next.js storefront](https://docs.medusajs.com/starters/nextjs-medusa-starter). 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](https://docs.medusajs.com/references/services/classes/NotificationService) 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](https://docs.medusajs.com/quickstart/quick-start/))
- Redis setup on your Medusa server ([Configuring Redis on your Medusa server](https://docs.medusajs.com/tutorial/set-up-your-development-environment/#redis))
- A webhook endpoint to which you can post webhooks (for testing purposes, I recommend using [Svix Play](https://play.svix.com/))

### Installing and Setting up the Webhooks Plugin

To install the plugin using NPM, run the following command in your Medusa server directory:

```bash
npm install medusa-plugin-webhooks
```

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

```bash
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:

```jsx
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:

```jsx
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](https://github.com/AnishDe12020/medusa-plugin-webhooks/issues).

- NPM Package - [medusa-plugin-webhooks](https://www.npmjs.com/package/medusa-plugin-webhooks)
- GitHub Repository - [AnishDe12020/medusa-plugin-webhooks](https://github.com/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](https://discord.gg/F87eGuwkTp).