Webhooks

A webhook tells your system that something changed in the store, a moment after it happened. Deliveries are signed by the Standard Webhooks scheme, so any of its libraries can check them.

Loading the search index…

Webhooks

Events

EventWhen it happens
order.createdAn order appears, from any sales channel.
order.updatedAn order changes: items, delivery, payment or status.
order.status_changedAn order moves to another status; previous_attributes.status is the status before.
order.paidAn order becomes paid, or is created already paid.
order.cancelledAn order is cancelled.
payment.createdA payment appears for an order: an invoice waiting for money or money already received.
payment.succeededThe money of a payment is received, including a payment created as already received, such as cash at the till.
payment.status_changedA payment moves to another status; previous_attributes.status is the status before the move.
payment.updatedA payment changes: status, amounts, refunds against it.
refund.createdA refund is made for an order.
refund.completedThe money of a refund is paid out, including a refund completed right away.
refund.status_changedA refund moves to another status; previous_attributes.status is the status before the move.
refund.updatedA refund changes: status or its entries against payments.
fiscal_document.createdA fiscal document is created: an invoice, a credit or a debit note.
fiscal_document.updatedA fiscal document changed.
fiscal_document.issuedThe tax authority issued the document: it has a number, an accounting date and its tax.
fiscal_document.failedIssuing failed or the tax authority refused it; previous_attributes.status is the status before.
fiscal_document.annulledAn invoice is annulled by a note and no longer counts for the sale.
tax_period.status_changedA tax period was closed or reopened; previous_attributes.status is the status before the change.
money_transaction.createdA money transaction was posted: income to or expense from an account.
money_transaction.updatedA money transaction changed: category, comment, amount or date.
money_transaction.deletedA money transaction was erased: a manual entry was deleted or a posting was withdrawn together with its document.
pos_shift.openedA register shift was opened.
pos_shift.closedA shift was closed: the drawer was counted and the difference was posted to the money journal.
pos_shift.updatedA shift changed, including a closed shift reconciled again after a late drawer movement.
pos_cash_movement.createdA cash drawer movement was recorded: a cash sale or refund, pay-in, pay-out, safe drop or reversal.
gift_card.createdA gift card was issued, by a sale or without one (compensation, promo). It becomes a liability once paid — see outstanding.
gift_card.updatedA gift card changed: balance, state, expiry or owner. Activation after payment arrives as this event.
gift_card_transaction.createdA gift card activity was recorded: issue, redemption, refund to the card, adjustment, void, block or balance transfer.
customer_account.createdA customer account was opened in the receivables book: credit limit, payment terms and status.
customer_account.updatedA customer account changed: the balance after each entry, the credit limit, payment terms, suspension or a move to another customer.
customer_account_entry.createdAn entry was recorded in a customer account: sale on account, payment, return, write-off, offset, withholding or reversal.
customer_account_entry.updatedA 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.createdA supplier was created: tax details and payment terms.
supplier.updatedA supplier changed: tax details, payment terms, activity or the link to its customer counterpart.
supplier.deletedA supplier was erased: only a supplier without documents can be erased.
supplier_bill.createdA supplier bill was created: a draft or a document posted right away (a delivery debt, a bill from a consignment settlement).
supplier_bill.updatedA supplier bill changed: draft edit, posting, approval for payment, receipt match or voiding.
supplier_bill.postedA 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.voidedA supplier bill was voided: it leaves payables and the purchase book, its payments are removed.
supplier_bill.deletedA supplier bill draft was erased. A posted document is not erased but voided.
supplier_bill_payment.createdA supplier bill was paid: by money, offset, credit note, purchase order advance, journal expense or outside the system.
supplier_bill_payment.updatedA supplier bill payment changed: a journal expense was reallocated between bills.
supplier_bill_payment.deletedA supplier bill payment was removed: cancelled, reversed together with an offset or with the bill voiding.
settlement_agreement.createdAn offset agreement with a supplier and a customer was created.
settlement_agreement.updatedAn offset agreement changed: contract details, term, schedule or the date of the next offset.
settlement_agreement.deletedAn offset agreement was deleted: no offset was ever posted under it.
settlement_offset.createdAn offset was posted: a customer debt was settled against the store's debt to a supplier.
settlement_offset.updatedAn offset changed: it was voided or the customer party was deleted.
settlement_offset.voidedAn offset was voided: its settlements were removed and the debts are open again.
purchase_order.createdA purchase order was created as a draft.
purchase_order.updatedA purchase order changed: its lines, the supplier answer, quantities received against it or the expected delivery.
purchase_order.status_changedA purchase order moved to another status: placed, partly or fully received, closed or cancelled; previous_attributes.status is the status before.
purchase_order.deletedA purchase order draft was erased. A placed order is cancelled, not erased.
goods_receipt.createdGoods were received from a supplier: the receipt is posted, stock and cost are updated.
goods_receipt.updatedA goods receipt changed: a correction of quantities or prices, or its delivery note details.
goods_receipt.voidedA goods receipt was reversed: the goods left stock and the delivery debt was voided.
supplier_return.createdA return to a supplier was created as a draft.
supplier_return.updatedA supplier return changed: its lines, a correction or the compensation received.
supplier_return.status_changedA supplier return moved to another status: shipped, closed or voided; previous_attributes.status is the status before.
supplier_return.deletedA supplier return draft was erased. A shipped return is voided, not erased.
consignment_settlement.createdA consignment settlement was created as a draft: the sales of the period collected for review with the supplier.
consignment_settlement.updatedA consignment settlement changed: its period or note, its lines rebuilt after a goods receipt correction, or a bill issued or released.
consignment_settlement.postedA consignment settlement was posted: the sales of the period are frozen into it, and the supplier invoices it.
consignment_settlement.voidedA consignment settlement was voided: its sales go into the next settlement. A settlement is voided, not erased.
tax_withholding.createdA 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.updatedA withholding register record changed: the provider adjusted the settlement amount, or the source or legal entity changed.
tax_withholding.annulledThe 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.deletedA 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.createdA product appears in the catalog.
product.updatedA product changes.
product.deletedA product is archived or erased.
inventory_level.updatedThe stock of a variant at a location changes or appears.
stock_movement.createdA movement is recorded in the stock journal: sale, receipt, write-off, stocktake, transfer or reversal.
stock_movement.updatedWhat 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.createdA product lot is added.
lot.updatedA lot changes: availability status, merge, number or expiry date.
lot.deletedA lot created by a stocktake and linked to nothing is removed.
location_transfer.createdA transfer of goods between locations is posted.
location_transfer.updatedTransfer lines are rewritten: a unit of measure change or a lot merge.
stocktake.createdA stock count of a location is started.
stocktake.status_changedA 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.updatedA stock count changes. Its lines are read from the /v1/stocktake-lines feed — they have no events of their own.
customer.createdA customer appears.
customer.updatedA customer changed, including their groups (group_ids).
customer.deletedA customer is deleted.
customer_group.createdA customer group appeared.
customer_group.updatedA customer group changed: name, description or activity. A change of members arrives as customer.updated of the customer.
customer_group.deletedA customer group was deleted; its members arrive as customer.updated.
price_list.createdA price list appeared: a location or wholesale list. A wholesale list reaches only apps with access to cost.
price_list.updatedA 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.deletedA price list was deleted together with its fixed prices and surcharges.
bulk_operation.finishedA 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.

Request
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:

Request
curl "https://api.saleya.app/v1/webhook-endpoints/14/secret" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Response
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.

Delivery to your endpoint
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
<?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.

Next guideAccounting through the API