Webhook Events in Medusa Cloud

Medusa Cloud now supports webhook events on all Launch and Scale plans. You can register an HTTPS endpoint in your organization settings and receive real-time event payloads for builds and deployments across all your projects.

This makes it possible to trigger downstream workflows based on Cloud activity. For example:

• Post deployment notifications to a Slack channel
• Update an internal status page when a build fails
• Kick off a testing pipeline when a deployment succeeds.

Configuring your endpoint

Add your endpoint URL under Webhooks > Endpoints in your organization settings. You will get the signing secret that you can use to verify events, and you can enable/disable the endpoint at any time. You can find more details in the docs.

Available events

Medusa Cloud currently delivers eight event types:

Build events: Copy to clipboardbuild.created, Copy to clipboardbuild.canceled, Copy to clipboardbuild.failed, Copy to clipboardbuild.succeeded

Deployment events: Copy to clipboarddeployment.created, Copy to clipboarddeployment.canceled, Copy to clipboarddeployment.failed, Copy to clipboarddeployment.succeeded

Each payload uses a consistent envelope structure: a unique event ID, the event type, a creation timestamp, and event-specific data. Payloads include build status, commit details (hash, message, author), and context objects for the organization, project, and environment.

123456789
{
  "id": "whev_01K2M7Q8ZCTVX3H4",
  "type": "deployment.created",
  "data": {
    // The payload of the event.
  },
  "created_at": "2026-08-07T09:14:22.000Z"
}

Delivery and retries

Medusa delivers events as HTTP POST requests. Your endpoint must respond with a Copy to clipboard2xx status within 10 seconds. If delivery fails, Medusa retries with exponential backoff starting at 5 minutes, for up to 24 hours.

Debugging events

The Events log in your organization settings shows every delivery attempt, and allows you to filter by time range, project, and environment. Each row displays the timestamp, event type, and one of three statuses:

• Pending / Back-off (orange): the event is awaiting delivery or scheduled for a retry
• Delivered (green): the event was successfully sent to your endpoint
• Failed (red): all delivery attempts were exhausted

Expanding a row gives you the full details you need to diagnose a failure: the targeted endpoint URL, the time of the most recent attempt, the failure reason (HTTP error, timeout, or network issue), the next scheduled retry time, and the associated project and environment. You also get the complete JSON payload, which lets you confirm the event structure without waiting for a successful delivery.

If you need to re-trigger an event without waiting for the next automatic retry, click the retry icon on any undelivered event. Medusa will attempt delivery immediately.

Verifying requests

Every request includes an Copy to clipboardX-Medusa-Signature header signed with HMAC-SHA256. To verify, compute the HMAC-SHA256 of Copy to clipboard{timestamp}.{raw_body} using your endpoint secret and compare the result against the Copy to clipboardv1 value using timing-safe comparison. You can find full examples in the documentation, but here's a snippet on how to implement verification in a Node.js app:

1234567891011121314151617181920
import crypto from "crypto"

export function isValid(
  rawBody: string,
  header: string,
  secret: string
) {
  const parts = new URLSearchParams(
    header.replace(/,/g, "&")
  )
  const timestamp = parts.get("t")
  const signature = parts.get("v1")

  if (!timestamp || !signature) {
    return false
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")

Get started

Webhook configuration is available in organization settings today. You can keep up to date with changes in our changelog.