Webhooks

Un webhook le avisa a tu sistema que algo cambió en la tienda, un momento después de que pasó. Las entregas se firman con el esquema Standard Webhooks, así que cualquiera de sus bibliotecas las verifica.

Cargando el índice de búsqueda…

Webhooks

Eventos

EventoCuándo ocurre
order.createdAparece un pedido, desde cualquier canal de venta.
order.updatedUn pedido cambia: ítems, envío, pago o estado.
order.status_changedUn pedido pasa a otro estado; previous_attributes.status es el estado anterior.
order.paidUn pedido queda pagado, o se crea ya pagado.
order.cancelledSe cancela un pedido.
payment.createdAparece un pago de un pedido: una factura que espera el dinero o dinero ya recibido.
payment.succeededSe recibe el dinero de un pago, también de un pago creado como ya recibido, como el efectivo en la caja.
payment.status_changedUn pago pasa a otro estado; previous_attributes.status es el estado anterior.
payment.updatedUn pago se modificó: estado, montos, reembolsos sobre él.
refund.createdSe hace un reembolso de un pedido.
refund.completedSe paga el dinero de un reembolso, también de un reembolso hecho en el momento.
refund.status_changedUn reembolso pasa a otro estado; previous_attributes.status es el estado anterior.
refund.updatedUn reembolso se modificó: estado o sus movimientos sobre los pagos.
fiscal_document.createdSe crea un comprobante fiscal: factura, nota de crédito o de débito.
fiscal_document.updatedUn comprobante fiscal cambió.
fiscal_document.issuedEl fisco emitió el comprobante: tiene número, fecha contable e impuestos.
fiscal_document.failedFalló la emisión o el fisco la rechazó; previous_attributes.status es el estado anterior.
fiscal_document.annulledUna factura se anuló con una nota y ya no vale para la venta.
tax_period.status_changedUn período fiscal se cerró o se reabrió; previous_attributes.status es el estado anterior.
money_transaction.createdSe asentó un movimiento de dinero: un ingreso a una cuenta o un egreso de ella.
money_transaction.updatedCambió un movimiento de dinero: categoría, comentario, importe o fecha.
money_transaction.deletedSe borró un movimiento de dinero: se eliminó una carga manual o se retiró un asiento junto con su comprobante.
pos_shift.openedSe abrió un turno de caja.
pos_shift.closedSe cerró un turno: se contó el cajón y la diferencia se asentó en el diario de dinero.
pos_shift.updatedCambió un turno, incluso un turno cerrado que se volvió a conciliar por un movimiento tardío del cajón.
pos_cash_movement.createdSe 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.createdSe emitió una tarjeta de regalo, con venta o sin ella (compensación, promo). Pasa a ser deuda al pagarse: mirá outstanding.
gift_card.updatedCambió una tarjeta de regalo: saldo, estado, vencimiento o titular. La activación tras el pago llega con este evento.
gift_card_transaction.createdSe 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.createdSe abrió la cuenta corriente de un cliente: límite de crédito, plazo de pago y estado.
customer_account.updatedLa 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.createdSe 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.updatedAl 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.createdSe dio de alta un proveedor: datos fiscales y condiciones de pago.
supplier.updatedCambió un proveedor: datos fiscales, condiciones de pago, actividad o el vínculo con su contraparte como cliente.
supplier.deletedSe borró un proveedor: solo se puede borrar un proveedor sin comprobantes.
supplier_bill.createdSe cargó un comprobante de proveedor: borrador o comprobante registrado de entrada (deuda por entrega, comprobante de una liquidación de consignación).
supplier_bill.updatedCambió un comprobante de proveedor: edición del borrador, registro, aprobación para pago, control contra la recepción o anulación.
supplier_bill.postedSe 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.voidedSe anuló un comprobante de proveedor: sale de cuentas a pagar y del libro de compras, y sus pagos se quitan.
supplier_bill.deletedSe borró un borrador de comprobante de proveedor. Un comprobante registrado no se borra: se anula.
supplier_bill_payment.createdSe 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.updatedCambió un pago de comprobante de proveedor: se redistribuyó un gasto del libro entre comprobantes.
supplier_bill_payment.deletedSe 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.createdSe creó un acuerdo de compensación con un proveedor y un cliente.
settlement_agreement.updatedCambió un acuerdo de compensación: datos del contrato, vigencia, calendario o fecha de la próxima compensación.
settlement_agreement.deletedSe eliminó un acuerdo de compensación: nunca se registró una compensación con él.
settlement_offset.createdSe registró una compensación: una deuda del cliente se canceló contra la deuda de la tienda con un proveedor.
settlement_offset.updatedCambió una compensación: se anuló o se eliminó el cliente de la operación.
settlement_offset.voidedSe anuló una compensación: se quitaron sus cancelaciones y las deudas vuelven a estar abiertas.
purchase_order.createdSe creó una orden de compra como borrador.
purchase_order.updatedCambió una orden de compra: sus líneas, la respuesta del proveedor, lo recibido contra ella o la entrega esperada.
purchase_order.status_changedUna 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.deletedSe borró un borrador de orden de compra. Una orden emitida no se borra: se cancela.
goods_receipt.createdSe recibió mercadería del proveedor: la recepción quedó registrada y se actualizaron el stock y el costo.
goods_receipt.updatedCambió una recepción: una corrección de cantidades o precios, o los datos del remito.
goods_receipt.voidedSe anuló una recepción: la mercadería salió del stock y se anuló la deuda por la entrega.
supplier_return.createdSe creó una devolución a proveedor como borrador.
supplier_return.updatedCambió una devolución a proveedor: sus líneas, una corrección o la compensación recibida.
supplier_return.status_changedUna devolución a proveedor pasó a otro estado: enviada, cerrada o anulada; previous_attributes.status es el estado anterior.
supplier_return.deletedSe borró un borrador de devolución a proveedor. Una devolución enviada no se borra: se anula.
consignment_settlement.createdSe creó una liquidación de consignación como borrador: las ventas del período armadas para revisar con el proveedor.
consignment_settlement.updatedCambió 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.postedSe registró una liquidación de consignación: las ventas del período quedan fijadas en ella y el proveedor la factura.
consignment_settlement.voidedSe 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.createdHay 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.updatedCambió un registro de retenciones: el proveedor ajustó el importe de la liquidación, o cambió el origen o la razón social.
tax_withholding.annulledLa 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.deletedSe 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.createdAparece un producto en el catálogo.
product.updatedUn producto cambia.
product.deletedUn producto se archiva o se borra.
inventory_level.updatedEl stock de una variante en un local cambia o aparece.
stock_movement.createdSe registra un movimiento en el diario de stock: venta, recepción, baja, inventario, traslado o reversión.
stock_movement.updatedCambió 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.createdSe crea un lote de producto.
lot.updatedSe modificó un lote: estado de disponibilidad, fusión, número o vencimiento.
lot.deletedSe quita un lote creado por un inventario y sin vínculos.
location_transfer.createdSe registra un traslado de mercadería entre locales.
location_transfer.updatedSe reescriben las líneas de un traslado: cambio de unidad de medida o fusión de lotes.
stocktake.createdSe abre un inventario de un local.
stocktake.status_changedNuevo estado de un inventario: en registro, registrado, anulado o de nuevo en borrador tras una falla. El estado anterior está en previous_attributes.
stocktake.updatedSe modifica un inventario. Sus líneas se leen en el feed /v1/stocktake-lines: no tienen eventos propios.
customer.createdAparece un cliente.
customer.updatedUn cliente cambió, también sus grupos (group_ids).
customer.deletedSe elimina un cliente.
customer_group.createdApareció un grupo de clientes.
customer_group.updatedUn grupo de clientes cambió: nombre, descripción o actividad. Un cambio de miembros llega como customer.updated del cliente.
customer_group.deletedSe eliminó un grupo de clientes; sus miembros llegan como customer.updated.
price_list.createdApareció una lista de precios: de local o mayorista. La mayorista llega solo a las apps con acceso al costo.
price_list.updatedUna 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.deletedSe eliminó una lista de precios junto con sus precios y recargos fijos.
bulk_operation.finishedTermina 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.

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

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

Entrega a tu 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 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
<?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-timestamp viejo, 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.

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.

Siguiente guíaContabilidad por API