Webhooks (experimental)

Looking to gather metrics for your pipelines? Gain insight into run durations and failures? Maybe you want to send Slack or Discord notifications? With our webhooks, all of these are possible!

When the notifier.webhookUrl setting is configured with an HTTPS URL, and moon is running in a CI environment, moon will POST a payload to this endpoint for every event in our pipeline.

Payload structure

Every webhook event is posted with the following request body, known as a payload.

type (string) - The type of event.
environment (object | null) - Information about the current CI/CD pipeline environment.
event (object) - The event specific payload. View each event for an example of their structure.
createdAt (string) - When the event was created, as a UTC timestamp in ISO 8601 (RFC 3339) format.
uuid (string) - A unique identifier for all webhooks in the current run batch.

{
  "type": "...",
  "environment": "...",
  "event": {
    // ...
  },
  "createdAt": "...",
  "uuid": "..."
}

The uuid field can be used to differentiate concurrently running pipelines!

Pipeline environment

When webhooks are sent from a CI/CD pipeline, we attempt to include information about the environment under the environment field. If information could not be detected, this field is null, otherwise it contains these fields.

baseBranch (string | null) - When a merge/pull request, the target (base) branch, otherwise null.
branch (string) - When a merge/pull request, the source (head) branch, otherwise the triggering branch.
id (string) - ID of the current pipeline instance.
provider (string) - Name of your CI/CD provider. GitHub Actions, GitLab, CircleCI, etc.
requestId (string | null) - The ID of the merge/pull request.
requestUrl (string | null) - Link to the merge/pull request.
revision (string) - The HEAD commit, revision, tag, ref, etc, that triggered the pipeline.
url (string | null) - Link to the current pipeline, when available.

View list of supported CI/CD providers.

Events

Pipeline

Runs actions within moon using a robust dependency graph. Is triggered when using moon run.

`pipeline.started`

Triggered when the pipeline has been created but before actions have started to run.

This event includes the number of actions registered within the pipeline, but does not provide detailed information about the actions. Use the action.* events for this.

{
  "type": "pipeline.started",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "actionsCount": 15
  },
  "uuid": "..."
}

`pipeline.finished`

Triggered when the pipeline has finished running all actions, with aggregated counts based on final status.

This event is not triggered if the pipeline crashes (this does not include actions that have failed, as those are legitimate runs). Use the pipeline.aborted event if you want to also catch crashes.

{
  "type": "pipeline.finished",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "cachedCount": 10,
    "baselineDuration": {
      "secs": 60,
      "nanos": 3591693
    },
    "duration": {
      "secs": 120,
      "nanos": 3591693
    },
    "estimatedSavings": {
      "secs": 60,
      "nanos": 0
    },
    "failedCount": 1,
    "passedCount": 4
  },
  "uuid": "..."
}

`pipeline.aborted`

Triggered when the pipeline has crashed for unknown reasons, or had to abort as a result of a critical action failing.

{
  "type": "pipeline.aborted",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "error": "..."
  },
  "uuid": "..."
}

Actions

Actions are "jobs" within the pipeline that are executed topologically.

`action.started`

Triggered when an action within the pipeline has started to run.

{
  "type": "action.started",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "action": {
      "attempts": null,
      "createdAt": "...",
      "duration": {
        "secs": 0,
        "nanos": 3591693
      },
      "error": null,
      "label": "InstallNodeDeps(18.0.0)",
      "nodeIndex": 5,
      "status": "passed"
    },
    "node": {
      "action": "InstallDeps",
      "params": [
        {
          "platform": "Node",
          "version": "18.0.0"
        }
      ]
    }
  },
  "uuid": "..."
}

`action.finished`

Triggered when an action within the pipeline has finished running, either with a success or failure. If the action failed, the error field will be set with the error message.

{
  "type": "action.finished",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "action": {
      "attempts": null,
      "createdAt": "...",
      "duration": {
        "secs": 0,
        "nanos": 3591693
      },
      "error": null,
      "label": "InstallNodeDeps(18.0.0)",
      "nodeIndex": 5,
      "status": "passed"
    },
    "error": null,
    "node": {
      "action": "InstallDeps",
      "params": {
        "platform": "Node",
        "version": "18.0.0"
      }
    }
  },
  "uuid": "..."
}

`dependencies.installing`

Triggered when dependencies for a workspace or project have started to install. When targeting a project, the project field will be set, otherwise null for the entire workspace.

{
  "type": "dependencies.installing",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "project": {
      "id": "server"
      // ...
    },
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`dependencies.installed`

Triggered when dependencies for a workspace or project have finished installing. When targeting a project, the project field will be set, otherwise null for the entire workspace. If the install failed, the error field will be set with the error message.

For more information about the action, refer to the action.finished event. Installed deps can be scoped with the InstallDeps(...) labels.

{
  "type": "dependencies.installed",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "error": null,
    "project": null,
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`project.syncing`

Triggered when an affected project has started syncing its workspace state. This occurs automatically before a project's task is ran.

{
  "type": "project.syncing",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "project": {
      "id": "client"
      // ...
    },
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`project.synced`

Triggered when an affected project has finished syncing. If the sync failed, the error field will be set with the error message.

For more information about the action, refer to the action.finished event. Synced projects can be scoped with the SyncProject(...) labels.

{
  "type": "project.synced",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "error": null,
    "project": {
      "id": "client"
      // ...
    },
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`tool.installing`

Triggered when a tool within the toolchain has started downloading and installing.

This event is always triggered, regardless of whether the tool has already been installed or not. For an accurate state, use the action.finished event. If the status is "skipped", then the tool was already installed.

{
  "type": "tool.installing",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`tool.installed`

Triggered when a tool within the toolchain has finished installing. If the install failed, the error field will be set with the error message.

For more information about the action, refer to the action.finished event. Tools can be scoped with the SetupTool(...) labels.

{
  "type": "tool.installed",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "error": null,
    "runtime": {
      "platform": "Node",
      "version": "18.0.0"
    }
  },
  "uuid": "..."
}

`target.running`

Triggered when a target has started to run (via moon run).

{
  "type": "target.running",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "target": "app:build"
  },
  "uuid": "..."
}

`target.ran`

Triggered when a target has finished running. If the run failed, the error field will be set with the error message.

For more information about the action, refer to the action.finished event. Ran targets can be scoped with the RunTarget(...) and RunPersistentTarget(...) labels.

{
  "type": "target.ran",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "error": null,
    "target": "app:build"
  },
  "uuid": "..."
}

Targets

Targets to run. Each event contains a hash field, that is a unique SHA-256 identifier for the the target's hashed contents.

`target-output.cache-check`

Triggered when the pipeline is checking for a cached archive of the currently running target.

{
  "type": "target-output.cache-check",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "hash": "1f5205cdb0912e97190e08a6cf98e41804bf6824b0a325d315e8b488a12677b0",
    "target": "app:build"
  },
  "uuid": "..."
}

`target-output.archiving`

Triggered when the outputs of a task are being cached into a tarball archive. This archive will be stored within .moon/cache/outputs on the host machine.

This event does not trigger if the task has no outputs.

{
  "type": "target-output.archiving",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "hash": "1f5205cdb0912e97190e08a6cf98e41804bf6824b0a325d315e8b488a12677b0",
    "project": {
      "id": "app"
      // ...
    },
    "target": "app:build",
    "task": {
      "id": "build"
      // ...
    }
  },
  "uuid": "..."
}

`target-output.archived`

Triggered when the outputs of a task have been archived and stored in the .moon/cache/outputs directory. The archivePath field is an absolute path to this archive, but is unique to the host machine that the target ran on.

This event does not trigger if target-output.archiving did not run or failed to run.

{
  "type": "target-output.archived",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "archivePath": "...",
    "hash": "1f5205cdb0912e97190e08a6cf98e41804bf6824b0a325d315e8b488a12677b0",
    "project": {
      "id": "app"
      // ...
    },
    "target": "app:build",
    "task": {
      "id": "build"
      // ...
    }
  },
  "uuid": "..."
}

`target-output.hydrating`

Triggered when a target has a cache hit for the generated hash (a cached archive exists on the local file system) and the archive is being unpacked into the project directory at the defined outputs.

This event does not trigger if the task has no outputs, or there was a cache miss (no matching archive).

{
  "type": "target-output.hydrating",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "hash": "1f5205cdb0912e97190e08a6cf98e41804bf6824b0a325d315e8b488a12677b0",
    "project": {
      "id": "app"
      // ...
    },
    "target": "app:build",
    "task": {
      "id": "build"
      // ...
    }
  },
  "uuid": "..."
}

`target-output.hydrated`

Triggered when a target has hydrated a project with the contents of a cached archive. The archivePath field is an absolute path to this archive, but is unique to the host machine that the target ran on.

This event does not trigger if target-output.hydrating did not run or failed to run.

{
  "type": "target-output.hydrated",
  "createdAt": "...",
  "environment": "...",
  "event": {
    "archivePath": "...",
    "hash": "1f5205cdb0912e97190e08a6cf98e41804bf6824b0a325d315e8b488a12677b0",
    "project": {
      "id": "app"
      // ...
    },
    "target": "app:build",
    "task": {
      "id": "build"
      // ...
    }
  },
  "uuid": "..."
}

Payload structure​

Pipeline environment​

Events​

Pipeline​

pipeline.started​

pipeline.finished​

pipeline.aborted​

Actions​

action.started​

action.finished​

dependencies.installing​

dependencies.installed​

project.syncing​

project.synced​

tool.installing​

tool.installed​

target.running​

target.ran​

Targets​

target-output.cache-check​

target-output.archiving​

target-output.archived​

target-output.hydrating​

target-output.hydrated​