# Slack alerts

Route signup, payment, and subscription events to a Slack channel with an incoming webhook.

Slack alerts are admin-facing: they tell **you** that someone signed up or a
payment failed. They are configured once per organization and need no code.

Set the incoming webhook URL in the BuildBase console under **Settings →
Slack**, pick the events you care about, and messages start arriving.

Messages arrive as Slack Block Kit — a header, a summary line linking back to
the console, a divider, then labelled fields:

```text
New User Registered
─────────────────────────────
Alice Chen just signed up          [avatar]
─────────────────────────────
Email                 Signed up
alice@example.com     15 Aug 2026, 09:12 UTC
```

The name in the summary line is a link to that user's console record. Each
message also carries a plain-text `text` fallback — here
`New user registered: Alice Chen (alice@example.com)` — which is what Slack
shows in notifications and previews.

> **Note:**
  Create an [incoming webhook](https://api.slack.com/messaging/webhooks) in your
  Slack workspace and copy the URL. BuildBase validates it against Slack's hook
  URL format and ignores anything that does not match.


## Selecting events

54 events can be routed to
Slack, grouped in the console under these categories:

| Category               | Events | Covers                                                            |
| ---------------------- | ------ | ----------------------------------------------------------------- |
| Subscriptions & Trials | 10     | Created, upgraded, canceled, resumed, suspended, trial lifecycle  |
| Workflows              | 7      | Publish, pause, resume, instance completion and failure           |
| Credits & Quota        | 6      | Purchased, granted, revoked, expired, low balance, quota exceeded |
| Audience               | 6      | Membership, list changes, and compliance state                    |
| Users & Workspaces     | 5      | Registrations, blocks, workspace create and delete                |
| Organization           | 5      | Member invites, acceptances, removals                             |
| Authentication         | 5      | Sign-in and credential events                                     |
| Payments               | 3      | Succeeded, failed, action required                                |
| Campaigns              | 2      | Email campaign dispatch                                           |
| Email Infrastructure   | 2      | Sending domain and sender changes                                 |
| Billing                | 1      | Billing account changes                                           |

> **Note:**
  **An empty event selection means every event is enabled, not none.** The
  filter only applies when the list is non-empty. To stop alerts entirely,
  remove the webhook URL rather than clearing the event list.


## Delivery behavior

| Behavior                | Detail                                                                                             |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| **Transport**           | A single `POST` to the webhook URL with a Slack Block Kit payload                                  |
| **Timeout**             | 5 seconds                                                                                          |
| **Failures**            | Logged as a warning and discarded. Slack delivery never blocks or fails the originating request    |
| **Retries**             | None. A failed post is not queued or retried                                                       |
| **No webhook set**      | Silent no-op                                                                                       |
| **Invalid webhook URL** | Treated as unset — no error surfaces in the console                                                |
| **Names**               | Workspace and user names are resolved for the message, falling back to raw IDs if the lookup fails |

Messages link back to the console — user names link to
`/dashboard/admin/users/:id` and workspaces to
`/dashboard/admin/workspaces/:id` — so an alert is one click from the record.

Because delivery is fire-and-forget with no retry, treat Slack as an awareness
channel rather than an audit trail. For guaranteed delivery, subscribe to the
same events with [webhooks](/webhooks/overview), which have delivery logs and
retries.

## Slack alerts versus user notifications

These are two separate systems and they do not share configuration:

|                         | Slack alerts      | [User notifications](/notifications/overview) |
| ----------------------- | ----------------- | --------------------------------------------- |
| Audience                | Your team         | Your users                                    |
| Configured by           | Org admin, once   | Per event, per workspace                      |
| Channels                | One Slack channel | Email and push                                |
| Triggered by            | System events     | `bb.notification.send()` or system events     |
| Honors user preferences | No                | Yes, when the event is `userManaged`          |

## Next Steps

- [Notifications overview](/notifications/overview) — send email and push to users.
- [Webhooks & events](/webhooks/overview) — the same events with retries and delivery logs.