Skip to content

Post from a script or CI ​

An incoming webhook is a private address: send it a message in Slack's format and it appears in a channel, so a script, a cron job or a CI run can post without a full app.

Create the webhook ​

Admins can always do this. Members can when an admin lets them add apps (Settings › Integrations › Who can add apps). Members can only use channels they are in.

  1. Open Settings › Integrations.
  2. Under Apps, choose New app and name it, for example "Relay". Its messages carry this name and an App label. Skip this step if you already have an app for the job.
  3. Open the app. Under Incoming webhooks, choose New webhook.
  4. Pick the Channel and a Topic where posts land, for example "Deploys". The app joins the channel if it isn't there yet.
  5. Turn on Let posts choose another channel or topic only if one webhook should serve several places. It works only for channels the app is already in.
  6. Choose Create webhook and copy the address.

The address looks like this and is shown once:

https://connect.example.com/api/v1/hooks/<id>/<secret>

TIP

The address is the secret. Anyone who has it can post into the channel as the app. Keep it in your CI's secret store, not in the repository. If it leaks, revoke the webhook and make a new one.

The examples below assume the address is in $CONNECT_WEBHOOK_URL. A good post answers ok.

Plain text ​

sh
curl -X POST "$CONNECT_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deploy finished"}'

"Deploy finished" appears in the Deploys topic from Relay. Every post to the same topic name lands in the same topic.

Formatted text, a name and an icon ​

Slack's formatting works: *bold*, `code` and <https://example.com/runs/42|a link>.

sh
curl -X POST "$CONNECT_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "*Deploy finished* for `api` <https://example.com/runs/42|view run>",
    "username": "Deploy bot",
    "icon_emoji": ":rocket:"
  }'

username (up to 60 characters) and icon_emoji or icon_url change how this one post is labelled. The App label stays.

Attachments become one message: a title, the text and each field on its own line.

sh
curl -X POST "$CONNECT_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Deploy failed",
    "attachments": [{
      "title": "api, run 42",
      "title_link": "https://example.com/runs/42",
      "text": "Migration timed out",
      "fields": [
        {"title": "Branch", "value": "main", "short": true},
        {"title": "Commit", "value": "3f2a9c1", "short": true}
      ]
    }]
  }'

Block Kit works too. Sections, fields, dividers and context become the message. A button with a url becomes a link in the text:

sh
curl -X POST "$CONNECT_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Release 1.4 is ready",
    "blocks": [
      {"type":"section","text":{"type":"mrkdwn","text":"*Release 1.4* is ready"}},
      {"type":"actions","elements":[
        {"type":"button","text":{"type":"plain_text","text":"Open run"},"url":"https://example.com/runs/42"}
      ]}
    ]
  }'

Parts with no equivalent are flattened or dropped. A message may be up to 8,000 characters; longer text is cut.

Form data ​

Some tools can't send JSON. Send Slack's form variant instead: the JSON goes in a payload field.

sh
curl -X POST "$CONNECT_WEBHOOK_URL" \
  --data-urlencode 'payload={"text":"Nightly backup done"}'

Another channel or topic ​

If you turned on Let posts choose another channel or topic, add them to the address. Without that setting they are ignored.

sh
curl -X POST "$CONNECT_WEBHOOK_URL?topic=Nightly" \
  -H 'Content-Type: application/json' -d '{"text":"Backup done"}'

curl -X POST "$CONNECT_WEBHOOK_URL?channel=alerts" \
  -H 'Content-Type: application/json' -d '{"text":"Disk almost full"}'

The channel is named like alerts or #alerts, and the app must already be in it.

GitHub Actions: post when a deploy fails ​

Save the address as a repository secret named CONNECT_WEBHOOK_URL, then add a last step to the deploy job:

yaml
- name: Tell Connectdary the deploy failed
  if: failure()
  env:
    CONNECT_WEBHOOK_URL: ${{ secrets.CONNECT_WEBHOOK_URL }}
    RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
  run: |
    jq -n --arg text "Deploy of ${{ github.repository }} failed on ${{ github.ref_name }}" \
          --arg url "$RUN_URL" \
      '{text: $text, attachments: [{title: "Open the run", title_link: $url}]}' |
    curl -fsS -X POST "$CONNECT_WEBHOOK_URL?topic=Deploy%20failures" \
      -H 'Content-Type: application/json' -d @-

jq builds the JSON so quotes in a branch name can't break it. curl -f makes the step fail loudly if Connectdary refuses the post.

A cron job ​

sh
#!/bin/sh
# crontab: 0 3 * * * /opt/scripts/backup.sh
if /opt/scripts/dump-database.sh 2>/tmp/backup.err; then
  msg="Nightly backup finished"
else
  msg="Nightly backup FAILED: $(tail -n 1 /tmp/backup.err)"
fi
curl -fsS -X POST "$CONNECT_WEBHOOK_URL" -H 'Content-Type: application/json' \
  -d "$(jq -n --arg text "$msg" '{text: $text}')"

What an error looks like ​

The answer is a short word in plain text, not JSON.

You seeWhy
no_service (404)The address is wrong, or the webhook was revoked.
no_text (400)The post has no text, attachments or blocks.
invalid_payload (400)The body isn't JSON, or isn't a payload form field.
channel_not_found (404)?channel= names a channel the app isn't in.
action_prohibited (403)The app, or the workspace's apps, are switched off.
rate_limited (429)Too many posts, or too many wrong addresses from one IP.

Each answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. A webhook accepts 60 posts a minute by default. A busy app can also hit its own daily posts budget, which folds the extra posts quietly.

Admins can see failed posts, counted by reason with the last body sent, on the webhook's row in Settings › Integrations.

Limits ​

  • A webhook can't notify the whole channel. <!channel>, <!here> and @ mentions in a post are removed, so nobody is notified by them.
  • It posts into one channel, plus others only with the override setting.
  • It can't read anything. To read or search, use the API.
  • Every post is recorded in the audit log.