Documentation / Recipes / Recipes
A Telegram alert when a payment fails
Your Rails app writes the failed payment, and the message reaches you in a Telegram chat.
You get a Telegram message every time a payment fails in your Rails app, with a link to the details. The app writes the failure as an error-level log, a rule turns it into an alert, and your preferences send that alert to Telegram.
1. Create the project and the token
- In CloseYourIt create a project for the app, for example
shop. - In the project's settings create an ingest token.
- Copy two values: the secret
token, which starts withcyi_, and the project id.
The token is secret: keep it in the server's environment, never in the code.
2. Install the gem
# Gemfile
gem "closeyourit-ruby"
bundle install
3. Configure it
# config/initializers/closeyourit.rb
CloseYourIt.init do |c|
c.endpoint_url = "https://bugs.example.com"
c.token = ENV["CLOSEYOURIT_TOKEN"]
c.project_id = ENV["CLOSEYOURIT_PROJECT_ID"]
c.environment = Rails.env
end
Set CLOSEYOURIT_TOKEN and CLOSEYOURIT_PROJECT_ID in the environment of the deployed app, then deploy.
The gem sends nothing from the development and test environments. To try the recipe from your computer, add c.disabled_environments = [] to the block, and remove it when you are done.
4. Write the failed payment
Where your code charges the customer, write a log of level error when the charge fails:
def charge(order)
PaymentGateway.charge!(order)
rescue PaymentGateway::Error => e
CloseYourIt.log(:error, "Payment failed", order_id: order.id, reason: e.message)
raise
end
PaymentGateway stands for the library you already use. raise lets the error go on as before: CloseYourIt also records it in Errors, with the lines of code it went through.
Give attributes plain names, such as order_id and reason. Values whose name contains card, token, email or other sensitive words leave the app as [FILTERED], on purpose.
5. Connect Telegram
The bot is created once for the whole installation, by whoever manages the server:
- Create a bot with BotFather in Telegram.
- In
/opt/closeyourit/.envsetTELEGRAM_BOT_TOKEN,TELEGRAM_BOT_USERNAMEandTELEGRAM_WEBHOOK_SECRET, then runcloseyourit restart. - Register the bot once:
cd /opt/closeyourit
docker compose exec app bin/rails telegram:set_webhook
docker compose exec app bin/rails telegram:set_commands
Then each person connects their own chat:
- In Preferences → Notifications turn Telegram on and press Connect Telegram: the chat with the bot opens.
- In the chat, press Start.
- Back on the page, when you read "Connected as", the chat is ready.
6. Create the alert rule
- Open Alerts → Alert rules and press New rule.
- Name:
Payment failed. - Event: Error/fatal log.
- Project:
shop. Environment:production. - Group repeated alerts: for example 10 minutes, so a burst of failures becomes one message.
- Press Save rule.
The rule fires for every error or fatal log of that project. With this configuration the gem only sends the logs you write yourself, so keep the error level for things a person must look at.
7. Send the alert to Telegram
- Open Preferences → Notifications.
- Find the error log alert in the list: the search field finds it by name.
- In its Telegram column choose Every time.
Quiet hours hold back emails only: Telegram messages are not delayed.
8. Try it
Make a payment fail where the gem sends data, for example with a card your payment provider declines in test mode. Logs leave the app every 5 seconds: within a few seconds the message arrives in Telegram, with the link to the log. The same message is in Logs, with the Level filter on error.
If nothing arrives
- The app runs in
developmentortest: the gem stays silent there (see step 3). - The rule's Project or Environment does not match the app.
- In Preferences → Notifications the Telegram column of that alert is not Every time.
- Telegram does not show "Connected as": repeat step 5.