Webhooks Plugin (Medusa v1)

This plugin adds configurable webhooks to your Medusa v1 server:

• Admin UI to manage endpoints and auth keys, and to view delivery logs
• Subscribers for order.placed and product.updated
• Dispatcher that forwards events to configured destinations and stores response logs

Enable the plugin (local/staging/prod)

Edit backend/medusa-config.js and add:

const plugins = [
  // ... other plugins
  {
    resolve: "src/plugins/webhooks",
  }
]

Optionally gate by env var:

process.env.WEBHOOKS_ENABLED === "true" && {
  resolve: "src/plugins/webhooks",
  options: { headerName: "X-Webhook-Key" }
}

Run DB migrations

Creates three tables: webhook_endpoint, webhook_key, webhook_log. Run your project’s migration command, e.g.:

npm run migrate
# or
npm run typeorm -- migration:run

Start the server

cd backend
npm run build && npm run start

Configure in Admin

Open Admin and go to the Webhooks page (backend/src/admin/webhooks/page.tsx).

• Endpoints: add event (e.g. order.placed), method (POST default), URL, optional JSON headers, enabled flag
• Auth Keys: create a key; the latest enabled key is injected using headerName
• Logs: recent deliveries with status, duration, and truncated response

Default events

• order.placed
• product.updated

Add more in backend/src/plugins/webhooks/subscribers/webhook-subscriber.ts.

Admin API (mounted at /admin/webhooks)

• GET /endpoints
• POST /endpoints { url, method, event, headers, enabled }
• PUT /endpoints/:id
• DELETE /endpoints/:id
• GET /keys
• POST /keys { name, key, enabled }
• DELETE /keys/:id
• GET /logs?limit=&offset=

Local enablement checklist

1. Add plugin to medusa-config.js
2. Run migrations
3. Build & start backend
4. In Admin: create a key and an endpoint
5. Trigger an event and verify logs

Staging/Production notes

• Ensure outbound network access to webhook destinations
• Run migrations during deploy
• Configure WEBHOOKS_ENABLED=true if you gated it
• Adjust headerName if needed

Behavior & limits

• POST/PUT/PATCH send JSON body; GET/DELETE send payload as query params
• Endpoint-level headers can be set via the Admin form (JSON)
• Response bodies are truncated at 500 chars in logs
• Structured to ease future Medusa v2 migration