Webhook Notifications#

Semaphore has webhook-based notifications that are delivered upon the success or failure of a pipeline. When the criteria for notifications are met, Semaphore will send a HTTP POST payload to the webhook's configured URL. You can use them, for example, to implement alerts via Hubot, or keep track of your projects on a company dashboard.

Setting up webhook notifications for a project#

You can use your Endpoint URL to set up a notification on Semaphore, with the following command:

$ sem create notification [name] \
    --projects [project_name] \
    --webhook-endpoint [webhook-endpoint]

For example, if you have a project called web and you want to get a webhook notification for every finished pipeline on the master branch, use the following command:

$ sem create notification master-pipelines \
    --projects web \
    --branches master \
    --webhook-endpoint [webhook-endpoint]

Setting up webhook notifications for multiple projects#

When creating a notification, you can specify multiple projects as the sources of your notifications.

For example, if your team manages three projects named web, cli, and api and you want to get notified of every finished pipeline on the master branch, use the following command:

$ sem create notifications teamA-notifications \
    --projects "web,cli,api" \
    --branches "master" \
    --webhook-endpoint [webhook-endpoint]

Filtering by project, branch, and pipeline names#

When creating a notification, you can specify filters for project, branch, and pipeline names.

For example, to send notifications for the master and staging branches, use the following command:

$ sem create notifications example \
    --branches "master,staging" \
    --webhook-endpoint [webhook-endpoint] \

A filter can either be a regex match or a direct match. Specifying a filter with forward slashes (e.g. /hotfix-.*/) defines a regex match, while a filter without forward slashes (e.g. master) defines a direct match.

$ sem create notifications example \
    --branches "master,/hotfix\/.*/" \
    --webhook-endpoint [webhook-endpoint] \

Matching can be specified for project and pipeline files as well. For example, if you want to get notified after every pipeline in a project that matches /.*-api$/ on the master branch when the prod.yml pipeline is executed, use the following command:

$ sem create notifications example \
    --projects "/.*api$/" \
    --branches "master" \
    --pipelines "prod.yml" \
    --webhook-endpoint [webhook-endpoint] \

Securing webhook notifications#

You should specify a secret token to sign the notification payload for security reasons. Thanks to this, you will be able to verify if incoming webhooks are coming from Semaphore.

As the first step, you will need to create a Semaphore Secret that will contain env WEBHOOK_SECRET with the value of your secret token.

You can learn more about using secrets in our Semaphore Secret documentation.

Later you can use this secret to sign webhooks. To do that, use the following command:

$ sem create notifications example \
    --webhook-endpoint [webhook-endpoint] \
    --webhook-secret [semaphore-secret-name]

Semaphore includes the signature in the X-Semaphore-Signature-256 header when the webhook secret is present.

Semaphore uses an HMAC-SHA256 to compute the signature of the request body.

Advanced notification setup#

In the previous examples we looked at simple use cases where we used the CLI interface to set up new notifications.

For more complex use cases, defining a notification YAML resource offers full control over the rules used for dispatching notifications.

Filtering by pipeline result#

You can specify notifications to be sent only upon specific pipeline results.

Available values for the results filter are:

  • passed
  • failed
  • stopped
  • canceled

Example YAML configuration:

# notify-on-fail.yml

apiVersion: v1alpha
kind: Notification
metadata:
  name: notify-on-fail
spec:
  rules:
    - name: "Example"
      filter:
        projects:
          - example-project
        results:
          - failed
      notify:
        webhook:
          endpoint: https://example.org/postreceiver

Note that you can list more than one value under results.

You can create a notification using the file above with the following command:

sem create -f notify-on-fail.yml

Modifying notification settings#

Notification settings can be listed, described, edited, and deleted within your organization using the sem command line tool.

  • 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]

See the sem command line tool documentation for further information regarding its use.

Setting up, editing, and deleting webhook notifications via the UI#

In the Configuration section of the sidebar, click on Notifications -> Create New Notification. Add the name of the notification and its rules, and click on the Save Changes button.

If you’d like to edit or delete an existing notification, click on the name of the notification, click on Edit or Delete... button in the top right corner, and follow the steps from there.

Notification payload#

The payload contains all the information related to a pipeline.

{
    "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/renderedtext/notifications",
        "slug": "renderedtext/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": {
  "head_repo_slug": "renderedtext/notifications",
  "number": 2,
  "name": "Add docs for webhook notifications",
  "head_sha": "9872252e00ac5a6b5870cdf94efe0e04770ad104",
  "branch_name": "webhook_notifications",
  "commit_range": "9872252e00ac5a6b5870cdf94efe0e04770ad104^..9872252e00ac5a6b5870cdf94efe0e04770ad104"
}

Sample tag object:

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

See also#