Skip to main content
Version: Cloud (SaaS)

Notifications

Get notified via Slack or any other webhook-based service when important things happen.

Slack and webhook notifications​

Send notifications to Slack and other webhook-based services. Notifications are sent when a pipeline finishes running so your team get instant feedback on the result.

To set up a Slack notification, first you need to configure an incoming webhook in your Slack workspace.

tip

Always use Incoming Webhooks app instead of creating your own Endpoint on Slack. If you set up a notification with an endpoint from your custom Slack app, you won't be able to use the channel override feature.

To create a notification, navigate to Notifications and press New Notification

  1. Type the name of the notification

  2. Type the name of the rule to fires the notification

  3. You can supply optional filters for this rule:

    • Projects: comma-separated list of projects where it applies
    • Branches: comma-separated list of Git branches
    • Pipelines: comma-separated list pipeline YAML files that need to run in order to fire the notification
    • Results: comma-separated list of results. Valid values are: "passed", "failed", "stopped", or "canceled"

    Show me

    Creating a new notification

note

Regular expressions must wrapped in forward slashes, e.g. /.*/ matches all values. You can use regular expressions in Projects, Branches, and Pipelines.

To send Slack notifications:

  1. Copy the Slack webhook for your Slack Workspace

  2. Type the comma-separated list of channels to receive the message

    Show me

    Adding an Slack webhook

To send notifications to other webhook-based services:

  1. Create a organization secret containing the environment variable WEBHOOK_SECRET and a secret value. Remember the name of this secret, e.g. "mywebhook-secret"

  2. Copy the URL of the webhook that receives the notification

  3. Type the name of the secret created on step 1, e.g. "mywebhook-secret"

    Show me

    Adding a webhook-based service

note

The value contained in the secret is sent along with the payload on notification to help secure the message. You can should validate that the secret value matches before accepting the message on the receiving end.

At this point, you can create additional rules or save the changes by pressing Save Notification.

Manage notifications from the CLI​

You can use the Semaphore command line tool to view, delete and edit notifications:

  • List notifications with: sem get notifications
  • Describe a notification with: sem get notifications <name>
  • Edit a notification with: sem edit notification <name>
  • Delete a notification with: sem delete notification <name>

Notification payload​

The payload contains all the information related to a pipeline.

Notification payload
{
    "version": "1.0.0",
    "organization": {
        "name": "semaphore",
        "id": "36360e31-fee6-42b2-9f6c-999d4c06ce81"
    },
    "project": {
        "name": "notifications",
        "id": "91e34570-bebe-42b6-b47a-ca710b2b8927"
    },
    "repository": {
        "url": "https://github.com/semaphoreci/myproject",
        "slug": "semaphoreci/notifications"
    },
    "revision": {
        "tag": null,
        "sender": {
            "login": "radwo",
            "email": "184065+radwo@users.noreply.github.com",
            "avatar_url": "https://avatars2.githubusercontent.com/u/184065?v=4"
        },
        "reference_type": "branch",
        "reference": "refs/heads/rw/webhook_impl",
        "pull_request": null,
        "commit_sha": "2d9f5fcec1ca7c68fa7bd44dd58ec4ff65814563",
        "commit_message": "empty",
        "branch": {
            "name": "rw/webhook_impl",
            "commit_range": "36ebdf6e906cf3491391442d2f779b512ca49485...2d9f5fcec1ca7c68fa7bd44dd58ec4ff65814563"
        }
    },
    "workflow": {
        "initial_pipeline_id": "fa02c7bd-7a8b-42e0-8d6e-aa0d8a194e19",
        "id": "acabe58e-4bcc-4d39-be06-e98d71917703",
        "created_at": "2019-12-10T13:09:54Z"
    },
    "pipeline": {
        "yaml_file_name": "semaphore.yml",
        "working_directory": ".semaphore",
        "stopping_at": "2019-12-10T13:10:22Z",
        "state": "done",
        "running_at": "2019-12-10T13:09:58Z",
        "result_reason": "user",
        "result": "stopped",
        "queuing_at": "2019-12-10T13:09:55Z",
        "pending_at": "2019-12-10T13:09:55Z",
        "name": "Notificaitons",
        "id": "fa02c7bd-7a8b-42e0-8d6e-aa0d8a194e19",
        "error_description": "",
        "done_at": "2019-12-10T13:10:28Z",
        "created_at": "2019-12-10T13:09:54Z"
    },
    "blocks": [
        {
            "state": "done",
            "result_reason": "user",
            "result": "stopped",
            "name": "List & Test & Build",
            "jobs": [
                {
                    "status": "finished",
                    "result": "stopped",
                    "name": "Test",
                    "index": 1,
                    "id": "21df03d2-c4e0-4e0a-acd7-5ff60dc0727e"
                },
                {
                    "status": "finished",
                    "result": "stopped",
                    "name": "Build",
                    "index": 2,
                    "id": "84190263-362c-4051-8260-e43637f148de"
                },
                {
                    "status": "finished",
                    "result": "passed",
                    "name": "Lint",
                    "index": 0,
                    "id": "d4b93a5b-69a5-43e6-ab24-06b095fc49bf"
                }
            ]
        }
    ]
}

In this example, revision.pull_request and revision.tag are null because the payload is related to a pipeline run started via a push to the branch. Information about this is kept in the revision.reference_type file.

Sample pull_request object:

Pull request object
"pull_request": {
  "head_repo_slug": "semaphoreci/notifications",
  "number": 2,
  "name": "Add docs for webhook notifications",
  "head_sha": "9872252e00ac5a6b5870cdf94efe0e04770ad104",
  "branch_name": "webhook_notifications",
  "commit_range": "9872252e00ac5a6b5870cdf94efe0e04770ad104^..9872252e00ac5a6b5870cdf94efe0e04770ad104"
}

Sample tag object:

Tag object
"tag": {
  "name": "v1.0.1",
}

See also​