Appearance
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
- An event happens (e.g. an order is paid).
- 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.
- Each of that admin's active gateways is checked against its filters. Matching gateways receive the notification and the delivery is logged.
Notification Feed
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
user_id | string | The admin this entry belongs to |
service_id | string | The service the event relates to |
reason | string | The event type (see Event Types) |
relevant_id | string | null | The primary ID of the entity involved (e.g. order ID, mandate ID) |
data | object | null | The event payload |
is_read | boolean | Whether the admin has read this entry |
created_at | datetime | When 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.
| Method | Path | Effect |
|---|---|---|
PATCH | /notifications/feed?is_read=true&reason=order_paid&service_id=svc_abc | Marks every matching entry read/unread |
DELETE | /notifications/feed?reason=order_paid&service_id=svc_abc | Removes 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.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
user_id | string | The admin who owns this gateway |
name | string | Human-readable label |
gateway_type | string | email, webhook, mattermost, or telegram |
is_active | boolean | Whether this gateway receives events |
service_ids | string[] | null | Optional restriction to specific services. null/empty means all services the admin has access to |
reasons | string[] | null | Optional restriction to specific event types. null/empty means all reasons |
created_at / updated_at | datetime | Timestamps |
Channel-specific fields
Each gateway_type requires its own set of fields - fields belonging to a different channel are rejected on creation/update.
gateway_type | Required fields | Description |
|---|---|---|
email | email | Recipient address |
webhook | webhook_url | URL TiruPay will POST to. A signing webhook_secret is auto-generated |
mattermost | mattermost_webhook_url | A Mattermost incoming webhook URL - the auth secret is embedded in the URL itself |
telegram | telegram_bot_token, telegram_chat_id | A 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
| Event | reason | service_id | Description |
|---|---|---|---|
| Order paid | order_paid | Order's service | An order was completed and paid |
| Order cancelled | order_cancelled | Order's service | An order was cancelled (draft or pending) |
| Order chargebacked | order_chargebacked | Order's service | A payment was revoked via chargeback/dispute |
| Order refunded | order_refunded | Order's service | An order was refunded |
| Payment failed | payment_failed | Order's service | A pending order's payment was declined |
| Paid order not delivered | order_not_delivered | Order's service | An order was paid, but the customer already owns what it sells (see Single Purchases). Nothing was delivered; refund the order |
| Mandate revoked | mandate_revoked | Mandate's service | A customer's SEPA/card mandate was revoked |
| Withdrawal received | withdrawal_received | Order's service | A new right-of-withdrawal request requires manual handling |
| Withdrawal completed | withdrawal_completed | Order's service | A withdrawal was completed (refund issued) |
| Withdrawal rejected | withdrawal_rejected | Order's service | A withdrawal request was rejected |
| Withdrawal overdue | withdrawal_overdue | Order's service | A withdrawal request has been waiting for processing for 10 days (sent once) |
| GDPR disclosure requested | gdpr_disclosure_requested | Subject's service(s) | A GDPR data disclosure was accessed |
| GDPR anonymization completed | gdpr_anonymization_completed | Subject's service(s) | A customer or user was anonymized (right to erasure) |
| Coupon fully used | coupon_fully_used | Coupon's service | A coupon reached its max_redemptions limit |
| Subscription upgraded | subscription_upgraded | Subscription's service | A subscription was upgraded (applied immediately) |
| Subscription downgraded | subscription_downgraded | Subscription's service | A subscription downgrade was scheduled |
| Subscription cancelled | subscription_cancelled | Subscription's service | A subscription was cancelled |
| Subscription paused (payment failure) | subscription_paused_payment_failure | Subscription's service | A subscription was paused due to a failed renewal payment |
| Paying customer change dropped | paying_customer_change_dropped | Subscription's service | A scheduled paying customer change did not apply: its mandate became unusable, or the subscription was cancelled |
| Invoicing configuration error | invoicing_config_error | Order's service | Invoice creation failed due to a provider/configuration issue |
| Webhook delivery failed | webhook_delivery_failed | Registry's service | A Webhook delivery attempt did not succeed |
| Test | test | The gateway owner's context | Sent when triggering a manual test delivery |
Notification Logs
Every delivery attempt to a gateway is logged, regardless of success - mirrors Webhook Logs exactly.
| Field | Description |
|---|---|
notification_gateway_id | The gateway this delivery was attempted for |
notification_feed_entry_id | The feed entry this delivery was for |
payload | The exact payload that was sent |
response_status | The HTTP status code returned (-1 if the request failed entirely) |
response_body | The response body, if any |
request_header / response_header | Headers sent/received |
created_at | When 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
404on every notification endpoint.
Relationships
- Webhooks - The sibling service-facing system. A failed webhook delivery itself fires a
webhook_delivery_failednotification. - 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.