Notifications

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:

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:

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.

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.

First inspect the event catalog:

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, Metrics, and How deploys work to investigate the underlying event.