Skip to main content

Webhooks (experimental)

v0.17

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

Runner

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

runner.started

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

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

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

runner.finished

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

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

{
"type": "runner.finished",
"createdAt": "...",
"environment": "...",
"event": {
"cachedCount": 10,
"duration": {
"secs": 120,
"nanos": 3591693
},
"failedCount": 1,
"passedCount": 4
},
"uuid": "..."
}

runner.aborted

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

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

Actions

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

action.started

Triggered when an action within the runner 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 runner 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(...) 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 runner 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": "..."
}