Events
| Event | When it happens |
|---|---|
order.created | An order appears, from any sales channel. |
order.updated | An order changes: items, delivery, payment or status. |
order.status_changed | An order moves to another status; previous_attributes.status is the status before. |
order.paid | An order becomes paid, or is created already paid. |
order.cancelled | An order is cancelled. |
payment.created | A payment appears for an order: an invoice waiting for money or money already received. |
payment.succeeded | The money of a payment is received, including a payment created as already received, such as cash at the till. |
payment.status_changed | A payment moves to another status; previous_attributes.status is the status before the move. |
payment.updated | A payment changes: status, amounts, refunds against it. |
refund.created | A refund is made for an order. |
refund.completed | The money of a refund is paid out, including a refund completed right away. |
refund.status_changed | A refund moves to another status; previous_attributes.status is the status before the move. |
refund.updated | A refund changes: status or its entries against payments. |
fiscal_document.created | A fiscal document is created: an invoice, a credit or a debit note. |
fiscal_document.updated | A fiscal document changed. |
fiscal_document.issued | The tax authority issued the document: it has a number, an accounting date and its tax. |
fiscal_document.failed | Issuing failed or the tax authority refused it; previous_attributes.status is the status before. |
fiscal_document.annulled | An invoice is annulled by a note and no longer counts for the sale. |
tax_period.status_changed | A tax period was closed or reopened; previous_attributes.status is the status before the change. |
money_transaction.created | A money transaction was posted: income to or expense from an account. |
money_transaction.updated | A money transaction changed: category, comment, amount or date. |
money_transaction.deleted | A money transaction was erased: a manual entry was deleted or a posting was withdrawn together with its document. |
pos_shift.opened | A register shift was opened. |
pos_shift.closed | A shift was closed: the drawer was counted and the difference was posted to the money journal. |
pos_shift.updated | A shift changed, including a closed shift reconciled again after a late drawer movement. |
pos_cash_movement.created | A cash drawer movement was recorded: a cash sale or refund, pay-in, pay-out, safe drop or reversal. |
gift_card.created | A gift card was issued, by a sale or without one (compensation, promo). It becomes a liability once paid — see outstanding. |
gift_card.updated | A gift card changed: balance, state, expiry or owner. Activation after payment arrives as this event. |
gift_card_transaction.created | A gift card activity was recorded: issue, redemption, refund to the card, adjustment, void, block or balance transfer. |
customer_account.created | A customer account was opened in the receivables book: credit limit, payment terms and status. |
customer_account.updated | A customer account changed: the balance after each entry, the credit limit, payment terms, suspension or a move to another customer. |
customer_account_entry.created | An entry was recorded in a customer account: sale on account, payment, return, write-off, offset, withholding or reversal. |
customer_account_entry.updated | A customer merge moved the entry to the remaining customer account, or the entry lost its withholding certificate: the certificate was removed from the withholding register and tax_withholding_id became null. The entry amount does not change. |
supplier.created | A supplier was created: tax details and payment terms. |
supplier.updated | A supplier changed: tax details, payment terms, activity or the link to its customer counterpart. |
supplier.deleted | A supplier was erased: only a supplier without documents can be erased. |
supplier_bill.created | A supplier bill was created: a draft or a document posted right away (a delivery debt, a bill from a consignment settlement). |
supplier_bill.updated | A supplier bill changed: draft edit, posting, approval for payment, receipt match or voiding. |
supplier_bill.posted | A supplier bill was posted: from now on it is in payables and the purchase book. Also sent for a document created already posted. |
supplier_bill.voided | A supplier bill was voided: it leaves payables and the purchase book, its payments are removed. |
supplier_bill.deleted | A supplier bill draft was erased. A posted document is not erased but voided. |
supplier_bill_payment.created | A supplier bill was paid: by money, offset, credit note, purchase order advance, journal expense or outside the system. |
supplier_bill_payment.updated | A supplier bill payment changed: a journal expense was reallocated between bills. |
supplier_bill_payment.deleted | A supplier bill payment was removed: cancelled, reversed together with an offset or with the bill voiding. |
settlement_agreement.created | An offset agreement with a supplier and a customer was created. |
settlement_agreement.updated | An offset agreement changed: contract details, term, schedule or the date of the next offset. |
settlement_agreement.deleted | An offset agreement was deleted: no offset was ever posted under it. |
settlement_offset.created | An offset was posted: a customer debt was settled against the store's debt to a supplier. |
settlement_offset.updated | An offset changed: it was voided or the customer party was deleted. |
settlement_offset.voided | An offset was voided: its settlements were removed and the debts are open again. |
purchase_order.created | A purchase order was created as a draft. |
purchase_order.updated | A purchase order changed: its lines, the supplier answer, quantities received against it or the expected delivery. |
purchase_order.status_changed | A purchase order moved to another status: placed, partly or fully received, closed or cancelled; previous_attributes.status is the status before. |
purchase_order.deleted | A purchase order draft was erased. A placed order is cancelled, not erased. |
goods_receipt.created | Goods were received from a supplier: the receipt is posted, stock and cost are updated. |
goods_receipt.updated | A goods receipt changed: a correction of quantities or prices, or its delivery note details. |
goods_receipt.voided | A goods receipt was reversed: the goods left stock and the delivery debt was voided. |
supplier_return.created | A return to a supplier was created as a draft. |
supplier_return.updated | A supplier return changed: its lines, a correction or the compensation received. |
supplier_return.status_changed | A supplier return moved to another status: shipped, closed or voided; previous_attributes.status is the status before. |
supplier_return.deleted | A supplier return draft was erased. A shipped return is voided, not erased. |
consignment_settlement.created | A consignment settlement was created as a draft: the sales of the period collected for review with the supplier. |
consignment_settlement.updated | A consignment settlement changed: its period or note, its lines rebuilt after a goods receipt correction, or a bill issued or released. |
consignment_settlement.posted | A consignment settlement was posted: the sales of the period are frozen into it, and the supplier invoices it. |
consignment_settlement.voided | A consignment settlement was voided: its sales go into the next settlement. A settlement is voided, not erased. |
tax_withholding.created | A new record in the withholding register: tax was withheld from the store (settlement provider, bank, customer acting as an agent) or the store withheld it when paying a supplier — the side is in direction. |
tax_withholding.updated | A withholding register record changed: the provider adjusted the settlement amount, or the source or legal entity changed. |
tax_withholding.annulled | The store annulled its withholding certificate: the amount is no longer to remit, and the number stays taken. Comes together with tax_withholding.updated. |
tax_withholding.deleted | A record was removed from the withholding register: a manual entry, a withholding cleared by a provider reversal, or a payment certificate on a customer account entry reversal. |
product.created | A product appears in the catalog. |
product.updated | A product changes. |
product.deleted | A product is archived or erased. |
inventory_level.updated | The stock of a variant at a location changes or appears. |
stock_movement.created | A movement is recorded in the stock journal: sale, receipt, write-off, stocktake, transfer or reversal. |
stock_movement.updated | What the feed returns for a stock movement changed: the link to a deleted document was cleared, the order was moved, the quantity was rescaled on a unit change. |
lot.created | A product lot is added. |
lot.updated | A lot changes: availability status, merge, number or expiry date. |
lot.deleted | A lot created by a stocktake and linked to nothing is removed. |
location_transfer.created | A transfer of goods between locations is posted. |
location_transfer.updated | Transfer lines are rewritten: a unit of measure change or a lot merge. |
stocktake.created | A stock count of a location is started. |
stocktake.status_changed | A stock count changes status: handed over for posting, posted, cancelled or back to draft after a failure. The previous status is in previous_attributes. |
stocktake.updated | A stock count changes. Its lines are read from the /v1/stocktake-lines feed — they have no events of their own. |
customer.created | A customer appears. |
customer.updated | A customer changed, including their groups (group_ids). |
customer.deleted | A customer is deleted. |
customer_group.created | A customer group appeared. |
customer_group.updated | A customer group changed: name, description or activity. A change of members arrives as customer.updated of the customer. |
customer_group.deleted | A customer group was deleted; its members arrive as customer.updated. |
price_list.created | A price list appeared: a location or wholesale list. A wholesale list reaches only apps with access to cost. |
price_list.updated | A price list changed: its rule, rounding, a fixed price or surcharge. The prices themselves are in the price-list-items and price-list-modifier-items feeds. |
price_list.deleted | A price list was deleted together with its fixed prices and surcharges. |
bulk_operation.finished | A bulk operation of this app ends; only this app gets it. |
A record changed several times in one transaction gives one event. The same events are in the event feed for 30 days: read it to catch up after your endpoint was down.
Add an endpoint
Create an endpoint with the address and the events it wants. The address must be https on a public host; each event needs the read scope of its resource, orders:read for order.*. An app can have up to 10 endpoints. The store can do the same in the card of the app, on the Webhooks tab.
curl -X POST "https://api.saleya.app/v1/webhook-endpoints" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2918' \
-H "Content-Type: application/json" \
-d '{
"url": "https://erp.example.com/saleya/webhooks",
"description": "ERP",
"enabled_events": [
"order.created",
"order.paid",
"inventory_level.updated"
]
}'Then get the signing secret and keep it with the token:
curl "https://api.saleya.app/v1/webhook-endpoints/14/secret" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 200 OK
{
"endpoint_id": 14,
"secret": "whsec_c2FsZXlhLWd1aWRlLXNhbXBsZS1zZWNyZXQtMDAzMiE="
}A delivery
A delivery is a POST with the event as its body — the same object as in the event feed — and three headers: webhook-id, the ID of the event; webhook-timestamp, when the attempt was made; webhook-signature, the signature.
POST /saleya/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json
webhook-id: 4518
webhook-timestamp: 1794407400
webhook-signature: v1,70uXS7tBMWQWQJP0MhHc6+QvfBJlYQY9zlbIvyYLm28=
{
"id": 4518,
"type": "inventory_level.updated",
"created_at": "2026-11-11T14:30:00Z",
"actor": {
"type": "operator",
"id": null
},
"request_id": null,
"data": {
"id": 90211,
"object": {
"variant_id": 1042,
"location_id": 3,
"on_hand": "18",
"reserved": "2",
"available": "16",
"updated_at": "2026-11-11T14:30:00Z"
},
"previous_attributes": null
}
}data.object is the record as it was when the delivery was first sent, with the fields the scopes of the app allow; for an erased record it is null. Respond with any 2xx within 10 seconds; any other response, a redirect or no response is a failure.
Check the signature
The signature is v1, and a base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} with the secret — the base64 part after whsec_. Check it before you parse the body:
<?php
/**
* Checks a Saleya webhook delivery signed by the Standard Webhooks scheme.
*
* $payload — the raw request body, exactly as received.
* $headers — the request headers with lowercase names.
* $secret — the signing secret of the endpoint, whsec_...
*
* Returns the decoded event or throws when the headers, the time or the signature do not match.
*/
function verify_saleya_webhook(string $payload, array $headers, string $secret, int $toleranceSeconds = 300, ?int $now = null): array
{
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
$signatures = $headers['webhook-signature'] ?? '';
if ($id === '' || !ctype_digit($timestamp) || $signatures === '') {
throw new RuntimeException('Missing webhook headers');
}
if (abs(($now ?? time()) - (int) $timestamp) > $toleranceSeconds) {
throw new RuntimeException('Webhook timestamp is outside the tolerance');
}
$key = str_starts_with($secret, 'whsec_') ? base64_decode(substr($secret, 6), true) : false;
if ($key === false) {
throw new InvalidArgumentException('The secret must start with whsec_');
}
$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$payload}", $key, true));
foreach (explode(' ', $signatures) as $versioned) {
[$version, $signature] = array_pad(explode(',', $versioned, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $signature)) {
return json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
}
}
throw new RuntimeException('Invalid webhook signature');
}
- Sign the body exactly as it arrived: parsing and serializing JSON again changes the bytes.
- After a rotation the header has two signatures, separated by a space: the delivery is valid if one of them matches.
- Reject an old
webhook-timestamp, so that a captured delivery cannot be sent again later. - Compare in constant time, as the examples do.
Instead of these functions, any Standard Webhooks library works with the same secret.
Retries and failures
A failed delivery is retried up to 10 times with growing pauses, for about 72 hours. If an endpoint has no success for 72 hours, it is disabled and the store owner gets an email. A disabled endpoint is not sent new events: once it is enabled again, catch up from the event feed, which keeps them for 30 days.
- The delivery log of an endpoint shows what was sent, what waits and what failed, with the responses of your server.
- Retry a delivery after fixing your side, without waiting for the next attempt.
- Send a test event,
ping, to check an endpoint. - Rotate the secret: the new one signs at once, the previous one keeps signing for 24 hours.
Handle duplicates and order
A delivery can come more than once — for example, when your server responded after the timeout — and deliveries of different events can come out of order. Remember the webhook-id of handled deliveries, and before overwriting a record compare its updated_at with your copy.
Respond quickly and do the work in a queue. Treat a webhook as a signal and the sync by cursor as the source of truth.