Notifications and connectors

Choose where project events appear: in-app notifications, Slack, email or your own endpoint. Configure destinations in Portal › Webhooks & connectors. For signed HTTP requests to your application, see Webhooks; the rules below for event types, filters, tests and retries apply to every connector.

In-app notifications

Each project has one in-app notification connector in Portal › Webhooks & connectors. It shows events in the notification bell and counts them as unread. New ones appear straight away for people with access to every asset in the project who have the portal open; people whose access covers only some folders see theirs when they next load a page. By default it subscribes to the event types that need attention, such as age-restricted, blocked, purged and failed assets, the upload and spend limits, member changes and failing connectors.

Edit it to choose which event types appear in the bell, or switch it off to stop new notifications. It can't be deleted, and it is never disabled automatically. Every event is still listed on Portal › Alerts & Events whatever this connector's settings. Test events add a sample notification marked as a test.

Slack

A Slack connector posts each event to one Slack channel as a message with the event's title, severity, details and a View in CalmLens button.

Create a Slack connector in Portal › Webhooks & connectors using an incoming webhook URL from Slack  for your chosen channel.

Anyone with the URL can post to the channel, so CalmLens stores it encrypted and only shows its last four characters afterwards. When updating a connector, leaving its webhook URL blank preserves the existing secret. Only Slack incoming webhook URLs are accepted: https://hooks.slack.com/services/…, or a GovSlack webhook on *.slack-gov.com.

If Slack reports that the webhook was revoked, the channel was deleted or archived, or posting isn't allowed, the delivery fails straight away with a message saying so. Create a new webhook and update the connector. Slack rate limits and outages are retried on the schedule under Deliveries and retries.

Email

An email connector sends each event to the recipients you choose, from contact@calmlens.com, one email per person. The email has the event's title, details and a View in CalmLens link, and says why the recipient is getting it.

Recipients must be members of the project, or owners of the project's organisation, with an email address. They are checked again every time an event is sent: someone who leaves the project stops receiving emails, even if the connector still lists them, and if none of the recipients qualify any more, the delivery fails with a message saying so. To stop someone's emails, remove them from the connector; recipients can ask a project administrator to do this.

To avoid flooding inboxes, each email connector sends at most 30 events a minute. Events beyond that are retried a minute or more later, on the schedule under Deliveries and retries.

Event types and permissions

Choose the events each connector handles. An empty selection subscribes to every event type, so you can save it only if you can see every type. See the event catalogue for all types.

Event types are grouped as assets, moderation, usage, team, API keys and connectors. Each type needs a project permission: you can only subscribe a connector to a type you can see, and the portal's Portal › Alerts & Events page and the events feed list only the types your role allows. For example, the team events need members:read, the API key events need api-keys:read and the connector failure events need connectors:read. The permission for each type is in the event types table.

Slack and email messages, like webhooks, leave out names, email addresses and other personal or account facts that the portal shows; see Personal and account data.

Filters

By default a connector receives every event of the types it subscribes to. Filters narrow that further: an event is sent only if it matches every filter you set, and a filter left empty matches everything.

  • Severity: high severity only skips low events.
  • Folders: only events about an asset in one of the chosen folders, or in a folder inside them. Events that aren't about an asset (usage, team and connector events), and assets outside every folder, don't match.
  • Moderation categories: only events that carry flagged categories, asset.classified and the moderation status events, with at least one of the chosen categories. Every other event type doesn't match.
  • Caused by: only events whose actor.type is one of the chosen kinds: user (a person, or an assistant acting for one), api-key, automated moderation or CalmLens itself (system). See Webhook payload.

Filters are applied when the event happens. Changing them doesn't affect deliveries already made.

Test a connector

Testing a connector in Portal › Webhooks & connectors sends it a synthetic event straight away. The test is a real delivery: a signed request to your webhook endpoint (checking the URL, your signature verification and your response), a message in your Slack channel, or an email to each recipient. It appears in the deliveries list marked as a test, and is not retried. Test events use example data for the type you choose, with { "key": "test", "value": true } added to facts.

Deliveries and retries

Every attempt to send an event to a connector is recorded as a delivery. The deliveries list in Portal › Webhooks & connectors shows each delivery's event, status, attempt count, the last response or error, and the next retry time, for every connector or one at a time. A delivery's details show every attempt with its time, status, response time and the start of the response; a webhook delivery also shows the request it sent. See Delivery details.

A failed delivery is retried up to 7 attempts in total, waiting about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours between attempts (roughly 20.6 hours overall). Webhooks lists which responses are retried.

You can disable a connector without deleting it. Deliveries still waiting for a retry fail once their connector is disabled or deleted.

Redeliver

Redelivering a delivery sends its event to the same connector again, for example after fixing your endpoint. This creates a new delivery with the usual retries; the original stays in the list. The connector must be turned on and still subscribe to the event's type, the event must match the connector's current filters and still be stored (see Retention), and tests can't be redelivered.

Automatic disabling

If 10 deliveries in a row to a connector fail for good, CalmLens turns the connector off and the portal shows why. A delivery fails for good when it runs out of retries or gets a response that isn't retried, so one outage that a delivery retries 7 times counts once, and any successful delivery starts the count again. When a connector is turned off this way, the project gets a connector.disabled event (sent to your other connectors and the notification bell, never to the failing connector) and the owners of the project's organisation are emailed. Fix the destination, test the connector, then turn it back on, which resets the count, and redeliver what you missed. In-app notifications are never turned off automatically.

Retention

Deliveries are kept for 30 days and events for 90 days, then deleted automatically. Redeliver within that time, and use the events API or your own storage if you need a longer history.

Last updated

Signing in

Signing out

Cookies on CalmLens

We use essential cookies for sign-in and security. With your permission, functional cookies remember your preferences and Google Analytics measures website use and signups. Optional ad measurement cookies link Google ad clicks to signups. Personalised advertising stays off. Manage cookies