---
title: "Owner notifications"
description: "Hear about signups, first payments, rewards, refunds and fraud flags by email, Slack, Pushover or a webhook, without building alerts."
canonical: "https://boltclaw.ai/docs/referral-notifications"
last-updated: "2026-11-05"
---

# Owner notifications

Hear about signups, first payments, rewards, refunds and fraud flags by email, Slack, Pushover or a webhook, without building alerts.

Bolt Claw can tell you and your team when something happens in a referral program, so you do
not have to build alerts from webhooks. Per program, you switch each event on or off for each
channel: email to the program's managers, your own Slack, your own Pushover, and a webhook event
for any other push service. Set it up on the program's
[**Settings**, **Notifications**](https://boltclaw.ai/dashboard/referrals?open=notifications)
section, or through the API (below).

## The events

| Event | When it fires |
|---|---|
| `invite_used` | A customer is attributed to a promoter: a link or a code was used. Never a click. |
| `first_payment` | A referred customer's first payment, and after a first payment of 0 (a free month), their first one above 0. |
| `reward_ready` | A reward that is not cash (credit, free months, a perk, a gift card) is ready to give. |
| `reward_given` | A reward was given, by hand, by your server or through your Stripe. |
| `reward_not_given` | A reward could not be given, was handed back to you by the Stripe worker, or expired. |
| `reversed_after_reward` | A payment was refunded or disputed after its reward was given or its commission approved. |
| `review_needed` | A fraud flag is waiting for a person, or one of a promoter's discount codes was used far more often than their links were clicked (nothing is held for that one: have a look). Its email switch is the review alert email of the fraud settings. |
| `reward_expiring` | A reward that is ready, waiting or claimable lapses within seven days, and again a day before, unless it is given (1.46.0). The same moments as the [`referral.grant.expiring`](https://boltclaw.ai/docs/webhooks) event. |

A click never sends anything, however many there are. A test event (from test mode, a test
referrer or a billing system's test sale) is sent like a live one, starting with "Test:".

## The channels

- **Email.** To the program's managers: everyone on your team who can manage referral
  programs. Anyone can mute one program for themselves on the same section ("Mute for me");
  they are asked again at every send, so a person who mutes hears nothing more from it. For
  `review_needed`, the email switch is the alert email of the program's fraud settings
  ([fraud and risk](https://boltclaw.ai/docs/referral-fraud#alerts)): one switch, two places.
- **Slack.** In Slack, create an app (or use an existing one), switch on **Incoming
  Webhooks**, add a webhook to the channel you want, and copy its URL: it is on Slack's
  `hooks.slack.com` host, under `/services/`. Paste it on the program's
  [**Settings**, **Notifications**](https://boltclaw.ai/dashboard/referrals?open=notifications)
  section. Bolt Claw keeps it encrypted, shows only its last four characters, and sends only
  to Slack's own address.
- **Pushover.** Your own Pushover account: create an application at pushover.net to get its
  application token, and copy your user key (or a group key) from your Pushover dashboard.
  Both are 30 letters and digits. Bolt Claw's own Pushover account never carries a
  merchant's messages; yours does, so the messages are in your account's limits and nobody
  else's.
- **Webhook.** A `referral.notification` event on your [webhook](https://boltclaw.ai/docs/webhooks) endpoints, for
  any other push service: ntfy, Gotify, a Discord or Teams relay, or your own code
  ([turning it into a push](https://boltclaw.ai/docs/webhooks#turning-referralnotification-into-a-push)). An
  endpoint limited to some programs hears only theirs.

**Send a test** on each channel sends the same kind of message, marked Test: the email goes to
you only, the others to the channel. A few tests an hour per channel.

## What the messages say

One sentence each, built from fixed words. In English:

- *New signup through an invite in Acme: customer user-42, invited by Jane.*
- *First payment in Acme: customer user-42, invited by your user user-7, made a first payment
  of 0.00 USD (their free month, nothing was paid).*
- *First paid payment in Acme: customer user-42, invited by Jane, paid 49.00 USD after a first
  payment of 0.00 USD.*
- *A reward is ready to give in Acme: 1 free month for the friend, customer user-42.*
- *A fraud flag waits for a person in Acme: a possible self-referral, for Jane. Their money
  waits until you decide.*

People are named as you know them: a customer by your own id for them, one of your users (a
referrer) by your id for them, and an affiliate by their name in the program. An affiliate's
email appears only in the email channel, and only when they chose to share it with the
program; Slack, Pushover and webhooks never carry an address. If your id for a customer or a
user is an email address, it too is written only in the email: elsewhere the message says
"id hidden: it is an email address" (a webhook's fields still carry your ids, as every referral
event does). A name is one line and never a link: `https://` and `www.` in a name are written
`https[:]//` and `www[.]`. A payment of 0 is said as one,
a discounted payment as "after the friend's discount", and no notification ever calls a
payment revenue, in any language. Each message links to the screen it is about, never to
anything with a token.

## Your own words for a person

Send a private `label` with a customer (a conversion's `customer.label`) or with one of your users
(`label` on `POST /v1/referrals/programs/{id}/referrers`): at most 80 characters on one line, such
as `jane@example.com Pro trial`. It is written after the person's id in every notification:

- *New signup through an invite in Acme: customer user-42 (jane@example.com Pro trial), invited by
  your user user-7 (Team lead).* (email)
- *... customer user-42 (jane@... Pro trial) ...* (Slack, Pushover and the webhook's sentence: an
  email address in a label is shortened to its first letters and `@...` outside email)

The last label you sent is kept, sealed, and used for your notifications only: no operation
returns it, no event body or export carries it, and nothing a promoter or a friend sees shows it.
It is erased with the person, and 25 months after you last sent it (the console's
`referrals.retention.customerFingerprintMonths`). Send `null` to remove it. A label is cleaned
like a name: never a link, never an invisible character.

## A link to your own admin

On the section, or as `admin_link` through the API, give an address on your own host with
`{external_id}` (your id for the person) and `{program_id}`, such as
`https://admin.example.com/users/{external_id}`. Each email, Slack and Pushover message then carries
a second link, *Open in your admin*, to the customer it names, or else to the one of your users it
names, beside Bolt Claw's own. Each value is percent-encoded, so it can never reach another host
or path; the address must start `https://`, has no user name and no placeholder in its host, and
nothing else is filled in. A notification about an affiliate only, a digest or a switched-off
channel has none. The webhook's body never changes: its fields carry the same ids, to build your
own link. An AI assistant may remove the link but never set or change it: it carries your people's
ids, and an approval page could not tell your host from another.

## Pushover's title, priority and sound

Per event, choose what a Pushover message shows and how it sounds (`pushover` through the API):

- `title`: `event` (what happened, the default), `program` (the program's name),
  `event_and_program`, or `custom` with your own `text` of up to 60 characters.
- `priority`: `-2` (no alert), `-1` (quiet), `0` (normal) or `1` (high, past quiet hours).
  Pushover's emergency priority, `2`, which repeats until somebody acknowledges it, is never sent.
- `sound`: one of Pushover's own sounds (`pushover`, `cashregister`, `magic`, `siren`, `none` ...).

`"pushover": { "first_payment": { "title": "custom", "text": "Ka-ching", "sound": "cashregister" } }`
sounds a cash register on each first payment; `null` for an event sends it as before.

## Who invited a customer, in every program

`GET /v1/referrals/customers/{external_id}` answers, for your own server and in every program your
key reaches that has seen the customer, when the program first saw them, when and how
(`link` or `discount_code`) they were referred, and by whom: one of your users by your own
`external_id`, a partner by their membership id and their name in the program, never an email.
For a screen the customer sees, the per-program
`GET /v1/referrals/programs/{id}/customers/{external_id}/referral` names the inviter only when
they agreed to it.

## In whose language

- **Email** is in each manager's own language: the one they chose in their account
  ([**Settings**, **Account**](https://boltclaw.ai/settings/account)), else the one their browser
  asked for when they first signed in. Two managers who read different languages get the same
  notification in two languages.
- **Slack, Pushover and the webhook** are in the program's notification language, set on the same
  section (or `locale` through the API, below); unset, the program's default language. A
  `referral.notification` webhook's `sentence` is in it; its ids and codes are the same in every
  language.
- A language Bolt Claw writes no notification words in reads as English. Amounts and dates follow
  the language (`49,00 USD` in German), names and ids are written as they are, and the monthly
  summary email follows each member's own language the same way.

## How many

Each channel of a program sends at most 20 messages in a clock hour (UTC), and fraud
notifications (`review_needed`) have 20 of their own, so a flood of signups never holds one
back; test notifications count apart from live ones. The rest of that hour arrive as one digest
a couple of minutes after it ends: *And 35 more in Acme in one hour (30 signups through
invites, 5 first payments): open the program to see them.* `per_hour` in the API says the
number in force.

`invite_used` and `first_payment` can come as one **daily digest** instead of one by one: a
message after each day (UTC) with how many of each there were.

A message that cannot be sent is tried again, five times in all. If Slack says the webhook no
longer exists (or refuses it), or Pushover says the token or the user key is invalid, that channel is
switched off with the reason shown on the section, and the program's managers are emailed
once. Paste a new webhook or token to switch it back on.

## Through the API

`GET /v1/referrals/programs/{id}/notifications` reads the switches, which channels are set
(their last four characters at most) and why one was switched off; `referrals:read`.
`PATCH` changes only what you send; `referrals:write`.

```bash
curl -X PATCH https://api.boltclaw.ai/v1/referrals/programs/PROGRAM_ID/notifications \
  -H "Authorization: Bearer $BOLTCLAW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": {
      "review_needed": { "email": true, "slack": true },
      "first_payment": { "slack": true, "digest": "daily" }
    },
    "channels": { "webhook": { "on": true } },
    "locale": "fr"
  }'
```

`locale` is the language of Slack, Pushover and the webhook (a tag such as `fr` or `pt-BR`, or
`null` for the program's default language); changing it asks nobody, and neither do `admin_link`
and `pushover`.

- **Credentials stay in the dashboard.** A Slack webhook URL or a Pushover token is never sent
  through the API: whoever holds one can post to your channel, and a secret never passes
  through a chat with an AI model. Switching Slack or Pushover on before its credential is set
  answers `409`.
- **Switching off is asked of a person when an AI assistant does it.** Switching an event or a
  channel on asks nobody. Switching anything off (any `false` in the body) from an assistant's
  key answers `428` with an approval link (`referral.notify.off`), and the approval page lists
  every switch it turns off: a notification switched off is how a fraud flag goes unseen. Your
  own server's key is not asked.
- Every change is in the activity log with the switches before and after, never a credential.

See the operations in [the referrals API reference](https://boltclaw.ai/docs/api/referrals) and the event in
[webhooks](https://boltclaw.ai/docs/webhooks).

<!-- https://boltclaw.ai/docs/referral-notifications as markdown. Generated from openapi.yaml; API version 1.53.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->
