Webhook

Un webhook es una herramienta que permite recibir notificaciones automáticas cuando ocurre un evento específico. Funciona registrando una URL HTTPS que actuará como receptor, a la cual se le enviará la información del evento en formato JSON. Es posible configurar webhooks para distintos tipos de eventos según la necesidad.

Categoría	Eventos
product	created/updated/deleted
order	created/updated/cancelled/paid/packed/shipped/fulfilled
customer	created/updated/deleted
category	created/updated/deleted
app	deleted

Para suscribirte al evento «product/created», por ejemplo, debes indicar ese valor en el campo «event». En términos generales, necesitas realizar una solicitud POST al endpoint de Webhooks, enviando en el body tanto el tipo de evento que querés recibir como la URL donde se enviarán las notificaciones.

Propiedades

Propiedad	Descripción
id	Id único del Webhook
url	La URL a la que el webhook debe enviar la solicitud POST cuando se produzca el evento.
event	El evento que activará el webhook
created_at	Fecha de creación del webhook
updated_at	Fecha de actualización del webhook

{ id: 35, event: 'product/updated', store_id: 1 }

Cuando se realiza una solicitud POST, todos los webhooks envían los siguientes parámetros en formato JSON:

store_id: Tienda desde la cual se originó el evento. event: Nombre del evento (product/created, product/updated, etc.).

category/created - category/updated - category/deleted

• id: Category's id.

customer/created - customer/updated - customer/deleted

• id: Customer's id.
• event_launch_ts: Timestamp at which the event was launched.

order/created - order/updated - order/paid - order/packed - order/shipped - order/fulfilled - order/cancelled

• id: Order's id.

order/packed se dispara cuando el estado de envío de la orden cambia a packaged.

order/shipped se dispara cuando el estado de envío de la orden cambia a shipped.

order/fulfilled se dispara cuando el estado de envío de la orden cambia a delivered.

app/deleted

Se dispara cuando la aplicación es desinstalada de una tienda. No incluye el campo id.

product/created - product/updated - product/deleted

• id: Product's id.

Ejemplo contenido del webhook

{
  "store_id": 1,
  "event": "product/created",
  "id": 16
}

Suscripción al evento order/fulfilled:

{ "url": "https://sunny-whale-33.webhook.cool", "event": "order/fulfilled" }

Payload recibido cuando una orden se marca como entregada:

{
  "store_id": 1,
  "event": "order/fulfilled",
  "id": 42
}

Suscripción al evento order/shipped:

{ "url": "https://sunny-whale-33.webhook.cool", "event": "order/shipped" }

Payload recibido cuando una orden se marca como enviada:

{
  "store_id": 1,
  "event": "order/shipped",
  "id": 42
}

Suscripción al evento app/deleted:

{ "url": "https://sunny-whale-33.webhook.cool", "event": "app/deleted" }

Payload recibido cuando la aplicación es desinstalada de una tienda:

{
  "store_id": 1,
  "event": "app/deleted"
}

Políticas de reintento

La política de reintentos de webhooks funciona de la siguiente manera: cuando ocurre un evento, el sistema envía el webhook de forma inmediata al endpoint configurado y espera hasta 3 segundos por una respuesta; si el endpoint responde con un código HTTP 2XX (por ejemplo 200 o 201), el envío se considera exitoso y no se realizan más intentos, pero si ocurre un error, timeout o se recibe una respuesta distinta de 2XX, el envío se considera fallido y se activa automáticamente la política de reintentos; en ese caso, el sistema vuelve a intentar la entrega siguiendo una estrategia progresiva donde los primeros intentos se realizan con intervalos de 0, 5, 10 y 15 minutos, y a partir del quinto intento se aplica un backoff exponencial multiplicando el intervalo previo por 1.4 (partiendo de una base de 15 segundos), lo que permite espaciar gradualmente los intentos para evitar sobrecargar el endpoint receptor; este proceso continúa hasta un máximo de 18 intentos, deteniéndose automáticamente en cuanto se recibe una respuesta exitosa o cuando se alcanza dicho límite.

Endpoints

GET /webhooks

Recibe una lista de todos los webhooks de tu aplicación.

Parámetros	Explicación
since_id	Limitar los resultados a los que se hayan publicado después del ID especificado
url	Muestra la url del webhook
event	Muestra el evento del webhook
created_at_min	Muestra los webhooks creados después de la fecha
created_at_max	Muestra los webhooks creados antes de la fecha
updated_at_min	Muestra los webhooks actualizados por última vez después de la fecha
updated_at_max	Muestra los webhooks actualizados por última vez antes de la fecha
page	Página que se va a mostrar
per_page	Número de resultados

GET /webhooks

HTTP/1.1 200 OK

{
  "status": 200,
  "data": [
    {
      "id": 35,
      "url": "https://sunny-whale-33.webhook.cool",
      "event": "order/cancelled",
      "created_at": "2026-04-29T14:45:13.000Z",
      "updated_at": "2026-04-29T14:45:13.340Z"
    },
    {
      "id": 31,
      "url": "https://sunny-whale-33.webhook.cool",
      "event": "order/paid",
      "created_at": "2026-04-28T18:15:43.000Z",
      "updated_at": "2026-04-28T18:15:42.630Z"
    }
  ],
  "error": []
}

GET /webhooks?since_id=31

HTTP/1.1 200 OK

{
  "status": 200,
  "data": [
    {
      "id": 35,
      "url": "https://sunny-whale-33.webhook.cool",
      "event": "order/cancelled",
      "created_at": "2026-04-29T14:45:13.000Z",
      "updated_at": "2026-04-29T14:45:13.340Z"
    }
  ],
  "error": []
}

GET /webhooks/{id}

Recibe solo un webhook

Parámetros	Explicación
fields	Lista de campos, separados por comas, que se deben incluir en la respuesta

GET /webhooks/35

HTTP/1.1 200 OK

{
  "status": 200,
  "data": {
    "id": 35,
    "url": "https://sunny-whale-33.webhook.cool"
  },
  "error": []
}

POST /webhooks

Crear un nuevo webhook

{ "url": "https://sunny-whale-33.webhook.cool", "event": "order/cancelled" }

HTTP/1.1 201 Created

{
  "status": 200,
  "data": {
    "success": true,
    "message": "Webhook saved",
    "data": {
      "id": 35,
      "url": "https://sunny-whale-33.webhook.cool"
    }
  },
  "error": []
}

PUT /webhooks/{id}

Modificar un webhook existente

PUT /webhooks/35

{
  "url": "https://jade-phoenix-07.webhook.cool",
  "event": "order/created"
}

HTTP/1.1 200 OK

{
  "status": 200,
  "data": {
    "id": 35,
    "installation_id": 3,
    "event_id": 7,
    "url": "https://jade-phoenix-07.webhook.cool",
    "created_at": "2026-04-29T14:45:13.000Z",
    "updated_at": "2026-04-29T20:19:01.537Z"
  },
  "error": []
}

DELETE /webhooks/{id}

Elimina un webhook DELETE /webhooks/35 HTTP/1.1 200 OK

{
  "status": 200,
  "data": {
    "msg": "Webhook deleted successfully"
  },
  "error": []
}