API: messages to your app
dhivi POS can tell your app the moment something happens at the key's shops, instead of your app asking again and again.
Turn it on
In the back office, open the key and fill in Tell my app when: your app's web address (https://…) and what to send. A message can be about anything the key may read:
| What | event | The key needs |
|---|---|---|
| A bill is made | pos.sale.completed | Sales — read |
| A bill is returned | pos.return.taken | Sales — read |
| Money owed is paid | pos.payment.collected | Sales — read |
| Stock changes | pos.stock.adjusted | Stock — read |
| A customer is added | pos.customer.created | Customers — read |
| A customer is changed | pos.customer.updated | Customers — read |
The first save shows the signing secret once. Copy it into your app.
What arrives
A POST to your address:
{ "id": 9001, "event": "pos.sale.completed", "occurredAt": "2026-10-22T06:41:02.000Z", "shop": "ADY001",
"data": { "saleId": 3391, "invoiceNo": "INV-3391", "total": 680, "itemCount": 2, "paymentMethod": "upi" } }data carries ids and amounts, never a name, phone or address — read the rest with the API if you need it.
Check it came from dhivi POS
Each message has two headers: x-zpos-timestamp (seconds) and x-zpos-signature (sha256= and a hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your signing secret). Work out the same and compare; refuse a timestamp more than five minutes old.
When your app does not answer
Answer 2xx quickly. Any other answer, or none, is tried again later — six times in all, waiting longer each time. Open the key in the back office to see the last messages and how each went.