Alerting | API PayStar.uk

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

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 STATUS UPDATED (Manualy)

ID 33 | PAYOUT STATUS UPDATED (Manualy)

ID 38 | STUCK ORDERS

ID 58 | ORDERS UNKNOWN (Instantly)

ID 54 | ORDERS UNKNOWN (Totaly, reporting 2 time a day)

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

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 | MERCHANT ADDED

ID 10 | MERCHANT UPDATED

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 | PIPELINE ADDED

ID 35 | PIPELINE STATUS UPDATED

ID 15 | PIPELINE KEYS UPDATED

Routing

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 | ROUTING RULE ADDED

ID 20 | ROUTING RULE UPDATED

ID 21 | ROUTING 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 | CHANNEL ADDED

ID 17 | CHANNEL UPDATED

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 | COMMISSION ADDED

ID 23 | COMMISSION UPDATED

ID 34 | COMISSION SETTINGS UPDATED

ID 24 | COMMISSION DELETED

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 30 | TEAM TIMEZONE UPDATED

ID 26 | USER ADDED

ID 27 | USER UPDATED

ID 29 | USER PASS UPDATED

ID 28 | USER DELETED

Settlements

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

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

https://head.paystar.uk/user | Notifications  | Settlements | Settlement Added & 
Settelment Changed Status & Cashier Added & 
Cashier Updated	& Cashier Deleted

ID 59 | SETTLEMENT ADDED

ID 60 | SETTLEMENT STATUS UPDATED

ID 61 | CASHIER ADDED

ID 62 | CASHIER UPDATED

ID 63 | CASHIER DELETED

Issue

These notifications are sent when an administrator manages Issue on the page: https://head.Issuetpaystar.uk/settlements

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

https://head.paystar.uk/user | Notifications  | Issue | 
Issue Added & Issue Updated & Issues reminder

ID 64 | ISSUE ADDED

ID 65 | ISSUE UPDATED

Events

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#

Payment#

Limits#

Merchant#

PipeLine#

Routing#

Channel#

Commission#

Team#

Settlements#

Issue#

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

Payment

Limits

Merchant

PipeLine

Routing

Channel

Commission

Team

Settlements

Issue