Eventos
| Evento | Cuándo ocurre |
|---|---|
order.created | Aparece un pedido, desde cualquier canal de venta. |
order.updated | Un pedido cambia: ítems, envío, pago o estado. |
order.status_changed | Un pedido pasa a otro estado; previous_attributes.status es el estado anterior. |
order.paid | Un pedido queda pagado, o se crea ya pagado. |
order.cancelled | Se cancela un pedido. |
payment.created | Aparece un pago de un pedido: una factura que espera el dinero o dinero ya recibido. |
payment.succeeded | Se recibe el dinero de un pago, también de un pago creado como ya recibido, como el efectivo en la caja. |
payment.status_changed | Un pago pasa a otro estado; previous_attributes.status es el estado anterior. |
payment.updated | Un pago se modificó: estado, montos, reembolsos sobre él. |
refund.created | Se hace un reembolso de un pedido. |
refund.completed | Se paga el dinero de un reembolso, también de un reembolso hecho en el momento. |
refund.status_changed | Un reembolso pasa a otro estado; previous_attributes.status es el estado anterior. |
refund.updated | Un reembolso se modificó: estado o sus movimientos sobre los pagos. |
fiscal_document.created | Se crea un comprobante fiscal: factura, nota de crédito o de débito. |
fiscal_document.updated | Un comprobante fiscal cambió. |
fiscal_document.issued | El fisco emitió el comprobante: tiene número, fecha contable e impuestos. |
fiscal_document.failed | Falló la emisión o el fisco la rechazó; previous_attributes.status es el estado anterior. |
fiscal_document.annulled | Una factura se anuló con una nota y ya no vale para la venta. |
tax_period.status_changed | Un período fiscal se cerró o se reabrió; previous_attributes.status es el estado anterior. |
money_transaction.created | Se asentó un movimiento de dinero: un ingreso a una cuenta o un egreso de ella. |
money_transaction.updated | Cambió un movimiento de dinero: categoría, comentario, importe o fecha. |
money_transaction.deleted | Se borró un movimiento de dinero: se eliminó una carga manual o se retiró un asiento junto con su comprobante. |
pos_shift.opened | Se abrió un turno de caja. |
pos_shift.closed | Se cerró un turno: se contó el cajón y la diferencia se asentó en el diario de dinero. |
pos_shift.updated | Cambió un turno, incluso un turno cerrado que se volvió a conciliar por un movimiento tardío del cajón. |
pos_cash_movement.created | Se registró un movimiento del cajón: venta o devolución en efectivo, ingreso, retiro, depósito en la caja fuerte o anulación. |
gift_card.created | Se emitió una tarjeta de regalo, con venta o sin ella (compensación, promo). Pasa a ser deuda al pagarse: mirá outstanding. |
gift_card.updated | Cambió una tarjeta de regalo: saldo, estado, vencimiento o titular. La activación tras el pago llega con este evento. |
gift_card_transaction.created | Se registró un movimiento de la tarjeta de regalo: emisión, canje, devolución a la tarjeta, ajuste, anulación, bloqueo o traspaso de saldo. |
customer_account.created | Se abrió la cuenta corriente de un cliente: límite de crédito, plazo de pago y estado. |
customer_account.updated | La cuenta corriente de un cliente cambió: saldo después de cada movimiento, límite, plazo, suspensión o paso a otro cliente. |
customer_account_entry.created | Se registró un movimiento en la cuenta corriente de un cliente: venta a cuenta, cobro, devolución, baja por incobrable, compensación, retención o anulación. |
customer_account_entry.updated | Al unir clientes, el movimiento pasó a la cuenta corriente del cliente unificado, o el movimiento perdió su certificado de retención: el certificado se quitó del registro de retenciones y tax_withholding_id quedó en null. El importe no cambia. |
supplier.created | Se dio de alta un proveedor: datos fiscales y condiciones de pago. |
supplier.updated | Cambió un proveedor: datos fiscales, condiciones de pago, actividad o el vínculo con su contraparte como cliente. |
supplier.deleted | Se borró un proveedor: solo se puede borrar un proveedor sin comprobantes. |
supplier_bill.created | Se cargó un comprobante de proveedor: borrador o comprobante registrado de entrada (deuda por entrega, comprobante de una liquidación de consignación). |
supplier_bill.updated | Cambió un comprobante de proveedor: edición del borrador, registro, aprobación para pago, control contra la recepción o anulación. |
supplier_bill.posted | Se registró un comprobante de proveedor: desde ahora está en cuentas a pagar y en el libro de compras. También llega para un comprobante cargado ya registrado. |
supplier_bill.voided | Se anuló un comprobante de proveedor: sale de cuentas a pagar y del libro de compras, y sus pagos se quitan. |
supplier_bill.deleted | Se borró un borrador de comprobante de proveedor. Un comprobante registrado no se borra: se anula. |
supplier_bill_payment.created | Se pagó un comprobante de proveedor: con dinero, compensación, nota de crédito, anticipo de una orden de compra, gasto del libro o fuera del sistema. |
supplier_bill_payment.updated | Cambió un pago de comprobante de proveedor: se redistribuyó un gasto del libro entre comprobantes. |
supplier_bill_payment.deleted | Se quitó un pago de comprobante de proveedor: se canceló, se revirtió junto con la compensación o con la anulación del comprobante. |
settlement_agreement.created | Se creó un acuerdo de compensación con un proveedor y un cliente. |
settlement_agreement.updated | Cambió un acuerdo de compensación: datos del contrato, vigencia, calendario o fecha de la próxima compensación. |
settlement_agreement.deleted | Se eliminó un acuerdo de compensación: nunca se registró una compensación con él. |
settlement_offset.created | Se registró una compensación: una deuda del cliente se canceló contra la deuda de la tienda con un proveedor. |
settlement_offset.updated | Cambió una compensación: se anuló o se eliminó el cliente de la operación. |
settlement_offset.voided | Se anuló una compensación: se quitaron sus cancelaciones y las deudas vuelven a estar abiertas. |
purchase_order.created | Se creó una orden de compra como borrador. |
purchase_order.updated | Cambió una orden de compra: sus líneas, la respuesta del proveedor, lo recibido contra ella o la entrega esperada. |
purchase_order.status_changed | Una orden de compra pasó a otro estado: emitida, recibida en parte o por completo, cerrada o cancelada; previous_attributes.status es el estado anterior. |
purchase_order.deleted | Se borró un borrador de orden de compra. Una orden emitida no se borra: se cancela. |
goods_receipt.created | Se recibió mercadería del proveedor: la recepción quedó registrada y se actualizaron el stock y el costo. |
goods_receipt.updated | Cambió una recepción: una corrección de cantidades o precios, o los datos del remito. |
goods_receipt.voided | Se anuló una recepción: la mercadería salió del stock y se anuló la deuda por la entrega. |
supplier_return.created | Se creó una devolución a proveedor como borrador. |
supplier_return.updated | Cambió una devolución a proveedor: sus líneas, una corrección o la compensación recibida. |
supplier_return.status_changed | Una devolución a proveedor pasó a otro estado: enviada, cerrada o anulada; previous_attributes.status es el estado anterior. |
supplier_return.deleted | Se borró un borrador de devolución a proveedor. Una devolución enviada no se borra: se anula. |
consignment_settlement.created | Se creó una liquidación de consignación como borrador: las ventas del período armadas para revisar con el proveedor. |
consignment_settlement.updated | Cambió una liquidación de consignación: su período o nota, sus líneas rearmadas tras una corrección de la recepción, o se emitió o liberó el comprobante. |
consignment_settlement.posted | Se registró una liquidación de consignación: las ventas del período quedan fijadas en ella y el proveedor la factura. |
consignment_settlement.voided | Se anuló una liquidación de consignación: sus ventas entran en la próxima liquidación. Una liquidación no se borra: se anula. |
tax_withholding.created | Hay un registro nuevo en el registro de retenciones: se lo retuvieron a la tienda (proveedor de cobros, banco, cliente agente de retención) o lo retuvo la tienda al pagarle a un proveedor; el lado está en direction. |
tax_withholding.updated | Cambió un registro de retenciones: el proveedor ajustó el importe de la liquidación, o cambió el origen o la razón social. |
tax_withholding.annulled | La tienda anuló su certificado de retención: el importe ya no es a ingresar y el número sigue ocupado. Llega junto con tax_withholding.updated. |
tax_withholding.deleted | Se quitó un registro de retenciones: una carga manual, una retención revertida por el proveedor o el certificado de un cobro al anular el movimiento de la cuenta corriente. |
product.created | Aparece un producto en el catálogo. |
product.updated | Un producto cambia. |
product.deleted | Un producto se archiva o se borra. |
inventory_level.updated | El stock de una variante en un local cambia o aparece. |
stock_movement.created | Se registra un movimiento en el diario de stock: venta, recepción, baja, inventario, traslado o reversión. |
stock_movement.updated | Cambió lo que el feed devuelve de un movimiento de stock: se borró el vínculo a un documento eliminado, se movió el pedido o se reescaló la cantidad al cambiar la unidad. |
lot.created | Se crea un lote de producto. |
lot.updated | Se modificó un lote: estado de disponibilidad, fusión, número o vencimiento. |
lot.deleted | Se quita un lote creado por un inventario y sin vínculos. |
location_transfer.created | Se registra un traslado de mercadería entre locales. |
location_transfer.updated | Se reescriben las líneas de un traslado: cambio de unidad de medida o fusión de lotes. |
stocktake.created | Se abre un inventario de un local. |
stocktake.status_changed | Nuevo estado de un inventario: en registro, registrado, anulado o de nuevo en borrador tras una falla. El estado anterior está en previous_attributes. |
stocktake.updated | Se modifica un inventario. Sus líneas se leen en el feed /v1/stocktake-lines: no tienen eventos propios. |
customer.created | Aparece un cliente. |
customer.updated | Un cliente cambió, también sus grupos (group_ids). |
customer.deleted | Se elimina un cliente. |
customer_group.created | Apareció un grupo de clientes. |
customer_group.updated | Un grupo de clientes cambió: nombre, descripción o actividad. Un cambio de miembros llega como customer.updated del cliente. |
customer_group.deleted | Se eliminó un grupo de clientes; sus miembros llegan como customer.updated. |
price_list.created | Apareció una lista de precios: de local o mayorista. La mayorista llega solo a las apps con acceso al costo. |
price_list.updated | Una lista de precios cambió: su regla, redondeo, un precio o recargo fijo. Los precios están en los feeds price-list-items y price-list-modifier-items. |
price_list.deleted | Se eliminó una lista de precios junto con sus precios y recargos fijos. |
bulk_operation.finished | Termina una operación masiva de esta aplicación; solo la recibe esta aplicación. |
Un registro que cambió varias veces en una transacción da un solo evento. Los mismos eventos están en el feed de eventos durante 30 días: leelo para ponerte al día después de que tu endpoint estuvo caído.
Agregá un endpoint
Creá un endpoint con la dirección y los eventos que quiere. La dirección tiene que ser https en un host público; cada evento necesita el scope de lectura de su recurso, orders:read para order.*. Una aplicación puede tener hasta 10 endpoints. La tienda puede hacer lo mismo en la ficha de la aplicación, en la pestaña Webhooks.
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"
]
}'Después obtené el secreto de firma y guardalo junto al 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="
}Una entrega
Una entrega es un POST con el evento como cuerpo — el mismo objeto que en el feed de eventos — y tres encabezados: webhook-id, el ID del evento; webhook-timestamp, cuándo se hizo el intento; webhook-signature, la firma.
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 es el registro tal como estaba cuando se envió la entrega por primera vez, con los campos que permiten los scopes de la aplicación; para un registro borrado es null. Respondé con cualquier 2xx dentro de 10 segundos; cualquier otra respuesta, una redirección o la falta de respuesta es una falla.
Verificá la firma
La firma es v1, y un HMAC-SHA256 en base64 de {webhook-id}.{webhook-timestamp}.{body} con el secreto — la parte base64 después de whsec_. Verificala antes de interpretar el cuerpo:
<?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');
}
- Firmá el cuerpo exactamente como llegó: interpretar y volver a serializar el JSON cambia los bytes.
- Después de una rotación el encabezado trae dos firmas, separadas por un espacio: la entrega es válida si una coincide.
- Rechazá un
webhook-timestampviejo, para que una entrega capturada no se pueda reenviar más tarde. - Compará en tiempo constante, como hacen los ejemplos.
En lugar de estas funciones sirve cualquier biblioteca de Standard Webhooks con el mismo secreto.
Reintentos y fallas
Una entrega fallida se reintenta hasta 10 veces con pausas crecientes, durante unas 72 horas. Si un endpoint no tiene ningún éxito durante 72 horas, se desactiva y el dueño de la tienda recibe un email. A un endpoint desactivado no se le envían eventos nuevos: cuando lo vuelvan a activar, ponete al día con el feed de eventos, que los guarda durante 30 días.
- El registro de entregas de un endpoint muestra qué salió, qué espera y qué falló, con las respuestas de tu servidor.
- Reintentá una entrega después de corregir tu lado, sin esperar el próximo intento.
- Enviá un evento de prueba,
ping, para verificar un endpoint. - Rotá el secreto: el nuevo firma enseguida, el anterior sigue firmando durante 24 horas.
Duplicados y orden
Una entrega puede llegar más de una vez — por ejemplo, cuando tu servidor respondió después del timeout — y las entregas de eventos distintos pueden llegar desordenadas. Recordá el webhook-id de las entregas procesadas y, antes de sobrescribir un registro, compará su updated_at con tu copia.
Respondé rápido y hacé el trabajo en una cola. Tomá el webhook como una señal y la sincronización por cursor como la fuente de verdad.