Skip to content

Notifications ​

Notifications keep admins informed about meaningful business events on the services they manage - an order was paid, a withdrawal request came in, a subscription was cancelled, and more. Unlike Webhooks, which notify your service via HTTP, Notifications are aimed at the people who administer your TiruPay services.

Every admin gets a personal inbox (the Notification Feed), and can additionally configure any number of Notification Gateways to re-broadcast their feed to external channels - Email, Mattermost, Telegram, or a webhook of their own.

Notifications vs. Webhooks

Webhooks are for service-to-service data sync (e.g. keeping your backend in sync with payment status). Notifications are for alerting a human admin about something they may need to act on. The two systems are independent - the same event (e.g. a paid order) can fire both a webhook and a notification.

How it works ​

  1. An event happens (e.g. an order is paid).
  2. Every admin with access to the relevant service gets one entry in their notification feed. If an event relates to more than one service, an entry is created for each.
  3. Each of that admin's active gateways is checked against its filters. Matching gateways receive the notification and the delivery is logged.

Notification Feed ​

FieldTypeDescription
idstringUnique identifier
user_idstringThe admin this entry belongs to
service_idstringThe service the event relates to
reasonstringThe event type (see Event Types)
relevant_idstring | nullThe primary ID of the entity involved (e.g. order ID, mandate ID)
dataobject | nullThe event payload
is_readbooleanWhether the admin has read this entry
created_atdatetimeWhen the event occurred

A feed entry is strictly personal - an admin only ever sees their own entries.

Marking as read ​

PATCH /notifications/feed/{entry_id} with {"is_read": true} marks an entry read. This is the only mutable field.

Clearing an entry ​

DELETE /notifications/feed/{entry_id} removes an entry from the caller's own inbox.

Bulk operations ​

Both accept the same reason/service_id filters as the list endpoint, and only ever affect the caller's own entries. Omit both filters to affect the entire inbox.

MethodPathEffect
PATCH/notifications/feed?is_read=true&reason=order_paid&service_id=svc_abcMarks every matching entry read/unread
DELETE/notifications/feed?reason=order_paid&service_id=svc_abcRemoves every matching entry

Both return 204 No Content.

Notification Gateways ​

A gateway re-broadcasts an admin's feed entries to an external channel. Gateways are owned by the individual admin, not by a service - an admin can create as many as they like, e.g. one Email gateway covering all their services, plus a Telegram gateway scoped to just one.

FieldTypeDescription
idstringUnique identifier
user_idstringThe admin who owns this gateway
namestringHuman-readable label
gateway_typestringemail, webhook, mattermost, or telegram
is_activebooleanWhether this gateway receives events
service_idsstring[] | nullOptional restriction to specific services. null/empty means all services the admin has access to
reasonsstring[] | nullOptional restriction to specific event types. null/empty means all reasons
created_at / updated_atdatetimeTimestamps

Channel-specific fields ​

Each gateway_type requires its own set of fields - fields belonging to a different channel are rejected on creation/update.

gateway_typeRequired fieldsDescription
emailemailRecipient address
webhookwebhook_urlURL TiruPay will POST to. A signing webhook_secret is auto-generated
mattermostmattermost_webhook_urlA Mattermost incoming webhook URL - the auth secret is embedded in the URL itself
telegramtelegram_bot_token, telegram_chat_idA Telegram bot token plus the target chat ID

Bring your own bot

For Telegram, you create the bot yourself and provide the resulting token - TiruPay does not create or manage the bot for you, it only uses the token you supply to send messages.

Secrets are shown only once

telegram_bot_token and webhook_secret are only included in the response when the gateway is created (POST /notifications/gateway). Every other response - including fetching the gateway by ID and list responses - omits them. Store the value from the creation response immediately; there is no way to retrieve it again afterwards.

Filtering ​

Both service_ids and reasons are optional allow-lists:

  • service_ids: null - the gateway receives events for every service the owning admin has access to.
  • service_ids: ["svc_abc"] - only events for that service.
  • reasons: null - the gateway receives every event type.
  • reasons: ["order_paid", "withdrawal_received"] - only those event types.

Testing ​

POST /notifications/gateway/{gateway_id}/test sends a test event to the gateway. Like a real event, the attempt is logged in Notification Logs.

Event Types ​

Eventreasonservice_idDescription
Order paidorder_paidOrder's serviceAn order was completed and paid
Order cancelledorder_cancelledOrder's serviceAn order was cancelled (draft or pending)
Order chargebackedorder_chargebackedOrder's serviceA payment was revoked via chargeback/dispute
Order refundedorder_refundedOrder's serviceAn order was refunded
Payment failedpayment_failedOrder's serviceA pending order's payment was declined
Paid order not deliveredorder_not_deliveredOrder's serviceAn order was paid, but the customer already owns what it sells (see Single Purchases). Nothing was delivered; refund the order
Mandate revokedmandate_revokedMandate's serviceA customer's SEPA/card mandate was revoked
Withdrawal receivedwithdrawal_receivedOrder's serviceA new right-of-withdrawal request requires manual handling
Withdrawal completedwithdrawal_completedOrder's serviceA withdrawal was completed (refund issued)
Withdrawal rejectedwithdrawal_rejectedOrder's serviceA withdrawal request was rejected
Withdrawal overduewithdrawal_overdueOrder's serviceA withdrawal request has been waiting for processing for 10 days (sent once)
GDPR disclosure requestedgdpr_disclosure_requestedSubject's service(s)A GDPR data disclosure was accessed
GDPR anonymization completedgdpr_anonymization_completedSubject's service(s)A customer or user was anonymized (right to erasure)
Coupon fully usedcoupon_fully_usedCoupon's serviceA coupon reached its max_redemptions limit
Subscription upgradedsubscription_upgradedSubscription's serviceA subscription was upgraded (applied immediately)
Subscription downgradedsubscription_downgradedSubscription's serviceA subscription downgrade was scheduled
Subscription cancelledsubscription_cancelledSubscription's serviceA subscription was cancelled
Subscription paused (payment failure)subscription_paused_payment_failureSubscription's serviceA subscription was paused due to a failed renewal payment
Paying customer change droppedpaying_customer_change_droppedSubscription's serviceA scheduled paying customer change did not apply: its mandate became unusable, or the subscription was cancelled
Invoicing configuration errorinvoicing_config_errorOrder's serviceInvoice creation failed due to a provider/configuration issue
Webhook delivery failedwebhook_delivery_failedRegistry's serviceA Webhook delivery attempt did not succeed
TesttestThe gateway owner's contextSent when triggering a manual test delivery

Notification Logs ​

Every delivery attempt to a gateway is logged, regardless of success - mirrors Webhook Logs exactly.

FieldDescription
notification_gateway_idThe gateway this delivery was attempted for
notification_feed_entry_idThe feed entry this delivery was for
payloadThe exact payload that was sent
response_statusThe HTTP status code returned (-1 if the request failed entirely)
response_bodyThe response body, if any
request_header / response_headerHeaders sent/received
created_atWhen the delivery was attempted

No automatic retries

TiruPay does not automatically retry a failed notification delivery. Use the test endpoint to trigger a fresh delivery.

Logs are retained for 60 days and cleaned up automatically.

Delivery notes ​

  • Notifications are delivered asynchronously - expect a short delay between the event and the gateway receiving it.
  • A delivery that fails is not retried. The feed entry itself is unaffected either way.
  • Notifications are only ever delivered with an Admin account - there is no Service or User access to this feature; those roles receive a 404 on every notification endpoint.

Relationships ​

  • Webhooks - The sibling service-facing system. A failed webhook delivery itself fires a webhook_delivery_failed notification.
  • Orders & Subscriptions - Order and subscription lifecycle events are the largest source of notifications.
  • Right of Withdrawal - Withdrawal request/completion/rejection all fire notifications.
  • Coupons - Coupon exhaustion fires coupon_fully_used.
  • Invoicing - Invoice creation failures fire invoicing_config_error.