Alerting

INFO

Alerting keeps you informed about what’s happening inside the PayStar platform. When a limit is reached, a pipeline is disabled, or conversion drops, you’ll receive an instant notification.

To subscribe to Telegram notifications, just follow these steps:

Go to https://head.paystar.uk/user

Open Notifications

Enable Telegram and follow the on‑screen instructions.

If you want to use Slack, just contact us - we will add it to your account within a week.

Information below is technical

The information below is required for technical integration with your own endpoint.

To connect your endpoint, specify the endpoint URL where you want to receive notifications and confirm the addition by checking the box:

After confirmation, a lock icon will appear. Click it to obtain the Private Key, which is required for signature verification.

Each notification contains four important parts:

A unique alert type ID — for example, stuck orders are identified by ID 38.

Key fields with the essential data — presented as Name / Content pairs.

A textual description — the message you receive in Telegram or Slack.

A signature included in the HTTP header.

Example alert:

curl -X 'POST' 'https://yourCustomEndpoint/'
-H 'content-length: 609' 
-H 'content-type: application/json' 
-H 'accept-encoding: gzip, deflate' 
-H 'signature: fed44a3574827198b7ea93869123446322a9c6ec94a3c30a0719af2adb99 // Signature  
-H 'host: webhook.site' -d $
{
  "id": 9, // ID типа алерта
  "createdAt": "2025-09-03T11:45:11.9797606Z", // Date of creation
  "message": "<b>NEW MERCHANT</b>\r\n\r\n- Merch: <b>Test Merchant</b>\r\n- Time: <b>09/03/2025 11:45:11 UTC</b>\r\n\r\n#Merch #Dmitry", // Textual description
  "fields": [ //Key fields
    {
      "Name": "UserName",
      "Content": "Dmitry"
    },
    {
      "Name": "Merchant",
      "Content": "Test Merchant"
    },
    {
      "Name": "Time",
      "Content": "09/03/2025 11:45:11"
    }
  ]
}

Signature

INFO

The alert signature is built the same way as in Callbacks: take a few fields, join them with semicolons, append your secret, hash with SHA‑256, and send the result in the Signature header.

The only difference vs Callbacks is which fields are joined (see below).

What exactly is signed

For alerts, the canonical string is:

{CreatedAt};{Message};{PrivateKey}

CreatedAt — the exact ISO‑8601 string from the alert payload (e.g., 2025-09-03T11:45:11.9797606Z).

Message — the exact message field as received (preserve spaces, HTML tags, and newlines; do not re-wrap).

PrivateKey — the secret shown under the lock icon in the UI (per-endpoint).

In Callbacks, the canonical string is
externalId;status;amount;orderType;privatekey,
hashed with SHA‑256 and provided via the Signature header. Alerts use the same algorithm and header, but a different string to sign.

How the signature is produced (sender) and verified (receiver)

Build the canonical string
Concatenate exactly: CreatedAt, Message, PrivateKey, separated by single semicolons (;).
Do not trim, pretty‑print, or reformat any part.

Hash
Compute SHA‑256 over the UTF‑8 bytes of the canonical string.

Encode
Convert the hash to a hexadecimal string (recommend lower‑case).

Send
Put the result into the HTTP header Signature (header name is case‑insensitive).

Verify (your endpoint)

Parse the JSON body and read createdAt and message as received.

Recreate the canonical string and compute the expected signature.

Compare your computed value with the incoming Signature header using a constant‑time comparison.

If they match, the alert is authentic.

What is not part of the signature

id (alert type ID, e.g., 38 for “stuck orders”) — used for routing, not signed.

fields array — helpful metadata, not signed.

Any other headers (host, content-length, etc.) — not signed.

Tip: Because id is not signed, treat it as advisory metadata. If you need “type” integrity, you may cross‑check that id is consistent with the message template you expect for that type.

Canonicalization rules (important!)

No reformatting of CreatedAt: use the exact string (don’t convert to local time or change precision).

Preserve Message verbatim: keep HTML tags, spaces, and line breaks exactly as delivered. In JSON, \n or \r\n escape sequences become real newlines after parsing — use those characters as-is when signing.

Encoding: always use UTF‑8 when hashing.

Hex case: normalize both sides to lower‑case before comparing (or compare case‑insensitively).

Security recommendations

Replay protection: reject alerts where CreatedAt is older than (for example) 5 minutes from your server time.

Constant‑time compare: use language‑specific safe compare to avoid timing attacks.

Key management: rotate the PrivateKey via the lock icon if you suspect exposure.

Audit: log (createdAt, message, signature, endpointId) on failures to aid troubleshooting.

Code examples

Node.js

Python

C# (.NET 6+)

Alerting examples

Merchant

These notifications are sent when an administrator manages a merchant on the page https://head.paystar.uk/merchants

To subscribe to these events, please enable the corresponding flags in your personal area: https://head.paystar.uk/user | Notifications | Merchants | Merch Added/Edited

ID 9 | NEW MERCHANT

ID 10 | MERCHANT EDITED

ID 11 | MERCHANT DELETED

PipeLine

These notifications are sent when an administrator manages Merchant -> Pipeline on the page https://head.paystar.uk/merchants

To subscribe to these events, please enable the corresponding flags in your personal area: https://head.paystar.uk/user | Notifications | Merchants | Endpoint Added/Edited

ID 12 | NEW PIPELINE

ID 35 | PIPELINE STATUS CHANGED

ID 15 | PIPELINE KEYS REGENERATED

Pipeline rules

These notifications are sent when an administrator manages Merchant -> Pipeline -> Pipeline Rules on the page https://head.paystar.uk/merchants

To subscribe to these events, please enable the corresponding flags in your personal area: https://head.paystar.uk/user | Notifications | Merchants | PipelineCondition Added/Edited & Regenerate Endpoint keys

ID 19 | NEW PIPELINE RULE

ID 20 | PIPELINE RULE EDITED

ID 21 | PIPELINE RULE DELETED

Channel

These notifications are sent when an administrator manages Merchant -> Pipeline -> Channels on the page https://head.paystar.uk/merchants

To subscribe to these events, please enable the corresponding flags in your personal area: https://head.paystar.uk/user | Notifications | Merchants | Channel Added/Edited

ID 16 | NEW CHANNEL

ID 17 | CHANNEL EDITED

ID 18 | CHANNEL DELETED

Commission

These notifications are sent when an administrator manages Merchant -> Pipeline -> Channels on the page https://head.paystar.uk/commission-groups

To subscribe to these events, please enable the corresponding flags in your personal area:

https://head.paystar.uk/user | Notifications  | Commission | Commission Group Added/Edited & Commission Rule Added/Edited

ID 22 | NEW COMMISSION

ID 23 | COMMISSION CHANGED

ID 24 | COMMISSION CHANGED

ID 34 | COMISSION RULE CHANGED

Team

These notifications are sent when an administrator manages Merchant -> Pipeline -> Channels on the page https://head.paystar.uk/organization

To subscribe to these events, please enable the corresponding flags in your personal area:

https://head.paystar.uk/user | Notifications  | Organization | Organization Updated & User Added/Edited & Timezone Edited

ID 25 | TEAM UPDATED

ID 26 | NEW USER

ID 27 | USER ROLE UPDATED

ID 28 | USER DELETED

ID 29 | PASSWORD UPDATED

ID 30 | TIMEZONE UPDATED

Payment

These notifications are sent when an administrator manages Merchant -> Pipeline -> Channels on the pages:

https://head.paystar.uk/deposits

https://head.paystar.uk/withdrawals

ID 32 | DEPOSIT ORDER STATUS UPDATED

ID 33 | PAYOUT ORDER STATUS UPDATED

ID 38 | STUCK ORDERS

ID 54 | ORDERS UNKNOWN

Limits

These notifications are sent when an administrator manages Merchant -> Pipeline -> Channels on the page: https://head.paystar.uk/limits

To subscribe to these events, please enable the corresponding flags in your personal area: https://head.paystar.uk/user | Notifications | Limits | Limits Added & Limits Deleted & Limits Exceeded

ID 56 | NEW LIMIT

ID 55 | LIMIT EXCEEDED

ID 57 | LIMIT DELETED

How to subscribe to notifications via Custom endpoint#

Each notification contains four important parts:#

Signature#

What exactly is signed#

How the signature is produced (sender) and verified (receiver)#

What is not part of the signature#

Canonicalization rules (important!)#

Security recommendations#

Code examples#

Alerting examples#

Merchant#

PipeLine#

Pipeline rules#

Channel#

Commission#

Team#

Payment#

Limits#

How to subscribe to notifications via Custom endpoint

Each notification contains four important parts:

Signature

What exactly is signed

How the signature is produced (sender) and verified (receiver)

What is not part of the signature

Canonicalization rules (important!)

Security recommendations

Code examples

Alerting examples

Merchant

PipeLine

Pipeline rules

Channel

Commission

Team

Payment

Limits