What we do
Tools
Industries
Department
How we workLet's talk →
Home/Slack/Slack Webhook
Slack

How to Send a Slack Webhook Message, and What a Webhook Can't Do

A Slack incoming webhook is a URL tied to one channel. POST some JSON to it and a message appears. You get the URL from a Slack app's settings, and the first message takes about five minutes. Below: the setup, a payload you can paste, the other thing Slack calls a webhook, and what the error strings mean.

Get the URL, then post

Make the URL: create a Slack app (or open one you have), switch on incoming webhooks, add one, pick the channel and authorize.

api.slack.com/apps Incoming Webhooks Add New Webhook to Workspace

Send a message: curl -X POST -H 'Content-type: application/json' --data '{"text":"Build 412 passed"}' <your webhook URL>. Slack answers ok and the message shows up.

Want structure? Put a blocks array in the same JSON for Block Kit sections, fields and context lines. Keep a plain text value too, since it's what notifications show.

Two different things both get called a Slack webhook

Check which one you have before debugging. The URL gives it away.

hooks.slack.com/services/…

Incoming webhook (from an app)

  • Posts a message to the one channel chosen when it was created.
  • You send the whole message: text, blocks, attachments.
  • Works on any Slack plan.
  • The name and icon come from the app. The request can't change them.
hooks.slack.com/triggers/…

Workflow Builder webhook

  • Starts a workflow made with the From a webhook trigger. Paid plans only.
  • You send up to 20 flat variables (text, user ID, user email or channel ID), no nested JSON.
  • The workflow decides what happens: post a message, DM someone, or run more steps.
  • If the request leaves out a variable the workflow expects, the run fails.

Developers sending a finished message usually want the incoming webhook. People who want a non-developer to edit the wording later, or to add steps after the message, are better off with the workflow version. More on that builder on our Slack workflows page.

What the error Slack sent back means

A failed webhook call returns a short error string in the response body. These are the ones people hit.

invalid_payload or no_text

How you'll know: The request reached Slack but the body wasn't valid JSON, or had no text.

Fix: Send Content-type: application/json and a real JSON object. Watch shell quoting in curl, and escape quotes inside your message. If you only send blocks, add text as well.

no_service

How you'll know: A URL that used to work now fails on every call.

Fix: The webhook was removed, the app was uninstalled, or Slack revoked the URL. Slack actively looks for webhook URLs posted publicly, in a GitHub repo for example, and revokes them. Make a new one and keep it in a secret store.

channel_is_archived

How you'll know: Someone archived the channel the webhook was created for.

Fix: Unarchive it, or create a new webhook for the channel that replaced it. A webhook can't be pointed at a different channel after the fact.

action_prohibited or posting_to_general_channel_denied

How you'll know: Workspace settings block the post.

Fix: An admin has restricted posting, or posting to #general. Retrying won't help. Pick another channel or ask the admin.

too_many_attachments

How you'll know: A message built in a loop, one attachment per row.

Fix: The cap is 100 attachments. Summarise in one message and link to the full list, or split it over several posts.

Where a webhook runs out

It posts and that's all. The response is just ok, with no message timestamp, so you can't thread a follow-up onto it, edit it later, or delete it. If you need any of those, post with chat.postMessage and a bot token instead. It returns the timestamp. Our Slack API page covers that route.

Buttons need a server behind them. You can include Block Kit buttons in a webhook message, but a click is sent to the app's interactivity Request URL. Without something listening there, the button does nothing. At that point you're building a full app anyway.

One channel per URL, one message a second. Slack limits incoming webhooks to about one message per second, with short bursts allowed. A script that posts 200 rows in a loop gets throttled, and anything you didn't retry is gone. Sending to ten channels means ten URLs, and your code has to know which is which.

Nothing tells you a message didn't arrive. Slack doesn't retry for you. If your sender ignores the response, a failed alert just never shows up, and nobody notices until the day it mattered. If the tool sending the alert already has its own Slack app, use that. It usually handles retries better than a hand-rolled webhook.

Questions people ask

How do I create a Slack webhook URL?

Go to api.slack.com/apps, create an app or open an existing one, and open Incoming Webhooks. Switch on Activate Incoming Webhooks, click Add New Webhook to Workspace, choose the channel and click Authorize. The URL appears in the list on that page.

Can I use one Slack webhook for multiple channels?

Not an incoming webhook. Each URL posts only to the channel picked when it was made, and the request can't override that. Make one webhook per channel, or post with chat.postMessage, which takes a channel ID on every call. A Workflow Builder webhook can take a channel ID as one of its variables, which is another way to choose the destination per request.

Is a Slack webhook URL a secret I need to protect?

Treat it like a password. Anyone who has it can post into that channel with no other check. Keep it out of code repositories and front-end code. Slack revokes URLs it finds leaked, and if you suspect one has leaked, remove it from the app's settings and make a new one.

What's the difference between an incoming webhook and a Slack bot?

A webhook sends messages into one channel and can't hear anything back. A bot uses a token with the Web API and the Events API, so it can post anywhere it's invited, read replies, respond to button clicks, and edit what it posted. Start with a webhook for one-way alerts and move to a bot when people need to answer it.

Why did my old Slack webhook URL stop working?

The usual causes: the app it belongs to was uninstalled or had incoming webhooks switched off, the webhook was deleted, the channel was archived, or Slack revoked the URL after finding it in public. The error string in the response body (no_service, channel_is_archived and so on) tells you which.

What is the rate limit on Slack webhooks?

About one message per second per webhook, with short bursts tolerated. Slack also limits any app to roughly one message per second per channel. Queue messages and send them at a steady pace rather than in a tight loop.

Can a Slack webhook message include buttons?

It can include them, but clicks go to the app's interactivity Request URL. You need a service there that checks Slack's signature, does the work and answers within three seconds. Without it, the buttons are decoration.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.