---
id: platform/notifications
title: Notifications
description: Configure personal deploy alerts, service overrides, push availability, and signed outbound event webhooks.
keywords: [bex, notifications, deploy alerts, webhooks, email]
last_updated: 2026-09-23
---

Bex supports personal deployment notifications and outbound webhooks for
machine integrations. Notification preferences and delivery infrastructure are
separate: enabling a preference does not configure SMTP, browser push, or a
mobile push provider on a self-hosted instance.

## Configure personal email preferences

Open notification settings in the dashboard, or use the caller-scoped API.
Set `BEX_API_URL` and an authorized `BEX_TOKEN` for the workspace:

```bash
curl --fail-with-body "$BEX_API_URL/v1/notification-settings" \
  -H "Authorization: Bearer $BEX_TOKEN"

curl --fail-with-body -X PATCH "$BEX_API_URL/v1/notification-settings" \
  -H "Authorization: Bearer $BEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deployStarted":false,"deploySucceeded":true,"deployFailed":true}'
```

These preferences belong to the current member, not every member of the
workspace. Send all three booleans when updating: the current handler decodes
omitted booleans as false. The default is failed-deploy email only.

Email needs the instance's mailer configuration and is best-effort; do not use
email delivery as an acknowledgment that an operational event was handled.
Invitations and required billing messages are separate from these preferences.

## Service-level overrides

A service can use `notificationsToSend` to override members' defaults:

| Value | Meaning |
| --- | --- |
| `default` | Use each member's personal preferences. |
| `none` | Suppress service deployment notifications covered by the policy. |
| `failure` | Notify for failures. |
| `all` | Notify for all covered deployment outcomes. |

Use the service settings control or
`GET`/`PATCH /v1/notification-settings/overrides/services/{serviceId}`.
The PATCH body contains `notificationsToSend`. Changing notification policy
does not deploy the service. Push has its own policy and delivery availability.

## Browser and mobile push

Where configured, Bex supports browser and native push destinations alongside
a notification inbox. Use the dashboard/device flow to grant permission and
register a destination; registration and delivery are not implied by email
settings. `GET /v1/notification-settings/push/availability` reports configured
push capability, and `GET /v1/notifications` reads the caller's inbox.

If a channel is shown as unavailable, its provider must be configured by the
instance operator. A saved preference alone cannot deliver through a missing
provider or a revoked browser/device subscription.

## Send events to your own endpoint

Outbound webhooks are implemented. They are distinct from incoming GitHub
webhooks and deploy hooks: Bex sends event notifications to your receiver.
Workspace administrators can create and manage endpoints through the dashboard
or `/v1/webhooks` API. For a full registration and delivery-identity walkthrough,
see [Outbound webhooks](./webhooks.md).

For webhook administration, `BEX_TOKEN` must represent an admin user with the
required OAuth scopes. A machine API-key token has the developer role and does
not grant webhook administration. See [API permissions](./api.md).

First inspect the event catalog:

```bash
curl --fail-with-body "$BEX_API_URL/v1/webhooks/event-types" \
  -H "Authorization: Bearer $BEX_TOKEN"
```

Create an endpoint with `POST /v1/webhooks`. Supply `ownerId`, `name`, `url`,
`enabled`, and an `eventFilter` array using supported event names. Review the
selected events and destination before enabling delivery. Bex blocks private,
loopback, and link-local destinations and does not follow redirects.

The creation response includes a signing secret **once**. Store it securely;
later reads do not return it. Verify Standard Webhooks signatures against the
raw request body before processing a delivery. Treat received payloads as
untrusted until verification succeeds, and keep the secret out of logs.

Deliveries can be retried and duplicated. Make processing idempotent using the
event identity. The payload contains event and resource identifiers; fetch any
additional authorized details through the Bex API rather than assuming full
resource state arrives in the event.

Inspect delivery history with `GET /v1/webhooks/{id}/events`. A failed attempt
can be resent with
`POST /v1/webhooks/{id}/events/{attemptId}/resend`. Repeated delivery failures
can disable an endpoint; fix the receiver and review its state before enabling
it again. Webhook delivery is asynchronous and should not be your only recovery
record.

## Troubleshoot a missing alert

Check the member's preferences, service override, selected channel availability,
and destination registration. For email, inspect mailer delivery diagnostics.
For webhooks, inspect the event filter, delivery history, endpoint state, TLS,
and receiver response. A successful deployment and a successful notification
are separate outcomes.

See [Logging](./logging.md), [Metrics](./metrics.md), and
[How deploys work](./how-deploys-work.md) to investigate the underlying event.