Webhooks (Cliente API)

Gestiona suscripciones de webhooks de forma programática con client.webhooks — listar, crear, actualizar y eliminar registros de webhooks.

client.webhooks permite que tu plugin gestione suscripciones de webhooks para la tienda de un comerciante a través de la API REST. Esta es la alternativa programática a declarar webhooks estáticamente en tu manifiesto whatalo.app.ts.

Para recibir y verificar payloads de webhooks, consulta la sección de Webhooks.

Permisos Requeridos

Operación	Permiso requerido
`list`	`read:webhooks`
`create`, `update`, `delete`	`write:webhooks`

Mapeo HTTP

Método	Verbo HTTP	Ruta
`list()`	GET	`/webhooks`
`create(data)`	POST	`/webhooks`
`update(id, data)`	PATCH	`/webhooks/:id`
`delete(id)`	DELETE	`/webhooks/:id`

Métodos

list

Obtiene todas las suscripciones de webhooks registradas para la tienda.

const webhooks = await client.webhooks.list();

webhooks.forEach((wh) => {
  console.log(`${wh.id}: ${wh.url} — events: ${wh.events.join(", ")}`);
});

create

Registra una nueva suscripción de webhook.

const webhook = await client.webhooks.create({
  url: "https://mi-plugin.com/api/webhooks",
  events: ["order.created", "product.updated"],
  secret: "mi-secreto-de-firma", // Used to verify HMAC signatures
});

console.log(webhook.id); // Store this ID to update or delete later

update

Actualiza las suscripciones de eventos de un webhook existente.

await client.webhooks.update("wh_123", {
  events: ["order.created", "order.updated", "order.cancelled"],
});

delete

Elimina una suscripción de webhook. El endpoint dejará de recibir eventos inmediatamente.

await client.webhooks.delete("wh_123");

Manifiesto vs. Registro por API

Los webhooks se pueden declarar de dos maneras:

Enfoque	Cuándo usarlo
Manifiesto `whatalo.app.ts` (campo `webhooks`)	Listas de eventos simples y estáticas conocidas al momento del despliegue
`client.webhooks.create` (API)	Suscripciones dinámicas que dependen de la configuración del comerciante o del plan

Para la mayoría de los plugins, el enfoque del manifiesto es más simple. Usa el enfoque de la API cuando los comerciantes necesiten elegir a qué eventos suscribirse desde la UI de configuración de tu plugin.

Manejo de Errores

import { ValidationError, AuthorizationError } from "@whatalo/plugin-sdk";

try {
  await client.webhooks.create({
    url: "no-es-una-url-valida",
    events: ["order.created"],
    secret: "mi-secreto",
  });
} catch (error) {
  if (error instanceof ValidationError) {
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else if (error instanceof AuthorizationError) {
    console.log(`Missing scope: ${error.requiredScope}`);
  } else {
    throw error;
  }
}

Consulta Errores y Límites de Tasa para la referencia completa de clases de error.

On this page