API para desarrolladores y MCP

Todo lo que gestione en la aplicación, también podrá gestionarlo desde su propio código o mediante un asistente de IA. Workflow Webhooks ofrece dos interfaces: una API REST y un servidor MCP. Ambas se encuentran en la página para desarrolladores.

Claves de API

Ambas plataformas se autentican mediante una clave de API. En la página «Desarrollador», en la sección «Claves de API», cree una clave y seleccione su nivel de acceso:

Solo lectura: listar webhooks, consultar el historial de invocaciones y las estadísticas.
Lectura y escritura: también permite crear, actualizar y eliminar webhooks.
Leer, escribir y ejecutar; además, puede lanzar una invocación de prueba o reproducir una anterior.

La clave completa se muestra una sola vez, en el momento de su creación. Cópiela entonces y guárdela en un lugar seguro; no podrá volver a verla. Las claves se almacenan en forma de hash, nunca en texto sin cifrar, y puede revocar una clave en cualquier momento.

Envíe la clave como un token «Bearer» en cada solicitud:

text

Authorization: Bearer fwk_your_key_here

¿Por qué la ejecución constituye un nivel independiente?

Al activar un Webhook se ejecutan efectivamente sus flujos de trabajo de Shopify Flow, y dichos flujos de trabajo pueden modificar su tienda: etiquetar pedidos, enviar correos electrónicos o actualizar el inventario. Mantener esto en un nivel independiente significa que una clave que usted facilite a un script o a un asistente de IA para las tareas cotidianas no podrá activar sus automatizaciones de forma accidental. Asigne claves de lectura de forma predeterminada y cree una clave de ejecución únicamente cuando sea realmente necesario.

URL base

La API y el servidor MCP se alojan en un nombre de host específico:

text

https://shopify.workflow-webhooks.app

Por lo tanto, la API REST se encuentra en https://shopify.workflow-webhooks.app/api/v1 y el servidor MCP, en https://shopify.workflow-webhooks.app/api/mcp. La página «Desarrollador» muestra ambos enlaces junto con un botón para copiarlos.

Este nombre de host solo aloja /api; la interfaz de administración integrada se mantiene en su propia URL registrada: Shopify. Mantenerlas separadas garantiza que la dirección que introduzca en un script, una tarea de CI o un cliente de IA sea estable y no dependa de la integración de la aplicación.

API REST

La URL base aparece en la página «Desarrollador». Los puntos finales principales son:

Método	Ruta	Nivel	Objetivo
OBTENER	`/api/v1`	ninguno	Índice de la API: confirma que la API está operativa
OBTENER	`/api/v1/me`	leer	Compruebe la autenticación y consulte el nivel de su clave
OBTENER	`/api/v1/webhooks`	leer	Listar webhooks
PUBLICAR	`/api/v1/webhooks`	escribir	Crear un webhook
OBTENER	`/api/v1/webhooks/:id`	leer	Obtenga un webhook
PUT / PATCH	`/api/v1/webhooks/:id`	escribir	Actualizar un webhook
BORRAR	`/api/v1/webhooks/:id`	escribir	Eliminar un webhook
PUBLICAR	`/api/v1/webhooks/:id/test`	ejecutar	Realice una llamada de prueba
OBTENER	`/api/v1/history`	leer	Lista de invocaciones
OBTENER	`/api/v1/history/:id`	leer	Obtenga una invocación, junto con su payload
PUBLICAR	`/api/v1/history/:id/replay`	ejecutar	Repetir una invocación anterior
OBTENER	`/api/v1/stats`	leer	Totales, índice de éxito, series diarias
OBTENER	`/api/v1/templates`	leer	Plantillas de webhooks integradas

Una comprobación rápida para ver si su llave funciona:

bash

curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"

json

{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

Servidor MCP

El servidor MCP permite que un asistente de IA (Claude, Cursor, VS Code, Gemini CLI y otros) interactúe con sus webhooks durante la conversación. En la página «Desarrollador», la pestaña «MCP» muestra la URL del servidor y un comando de conexión listo para copiar para cada cliente, con su clave ya introducida.

Las herramientas se corresponden con los puntos finales REST, y el conjunto de herramientas depende del nivel de su clave: una clave de solo lectura ni siquiera tiene acceso a las herramientas que permiten crear, eliminar o activar webhooks. Toda la autenticación y el tratamiento de datos se realizan en el lado del servidor.

Cómo se protegen sus datos

Hay dos aspectos que conviene tener en cuenta antes de utilizar un sistema de automatización o un asistente de IA con esta API.

El token de autenticación de su webhook nunca es legible. Ni el token ni el secreto de firma que configure en un webhook pueden recuperarse a través de la API o del MCP en ningún nivel. Las respuestas solo le indican si hay un token configurado (hasToken), pero nunca su valor. Puede configurar uno nuevo; nunca podrá recuperar el anterior.

Los datos personales incluidos en las cargas útiles se ocultan. Las cargas útiles de los webhooks proceden de sistemas externos y suelen contener datos de los clientes. Antes de que una payload de invocación salga del servidor, los valores que parecen datos personales se sustituyen por ***: direcciones de correo electrónico, números de teléfono, números de tarjeta y campos que llevan el nombre de una persona (customerName, shippingAddress y similares). Los encabezados de solicitud se depuran del mismo modo que lo hace la pantalla de historial de la aplicación.

Este enmascaramiento se realiza con cuidado, pero no constituye una garantía. Funciona con los nombres de los campos y los patrones de valores, por lo que los datos personales que se encuentren dentro de un campo de texto libre - una nota, un comentario o el cuerpo de un mensaje - podrían seguir siendo visibles. Considere que las respuestas de la API pueden contener datos de clientes y almacénelas en consecuencia.

Las pruebas y las reproducciones no consumen su cuota. Las invocaciones que realiza a través de la API se registran como pruebas, por lo que no se contabilizan dentro del límite mensual de su plan. Las reproducciones tampoco se contabilizan, ya que la invocación original ya lo hizo.

Próximos pasos

Introducción a Workflow Webhooks - cómo funcionan los webhooks y la asignación de payload.

Límites de frecuencia

La API REST y el servidor MCP comparten un único presupuesto por clave de API.

300 solicitudes por cada 60 segundos por clave, en una ventana fija.
Las llamadas de nivel de ejecución cuentan con un segundo presupuesto, más restrictivo, de 60 por hora. Se agotan ambos, por lo que un pico de ejecuciones también merma la asignación compartida. En el caso de esta aplicación, eso significa realizar una llamada de prueba a un webhook y reproducir una entrada del historial, dos acciones que, en realidad, ejecutan sus flujos de trabajo de Shopify Flow.
Es igual en todos los planes. Su plan limita el número de invocaciones, no de llamadas a la API, por lo que la actualización no aumenta estas cifras.
Se devuelve el código de estado HTTP 429. Espere un tiempo y vuelva a intentarlo, a ser posible con un retardo exponencial.
En caso de que nuestra caché no esté disponible durante un breve periodo de tiempo, el limitador se desactiva en lugar de bloquear su integración.

The incoming webhooks are not subject to frequency limits

Conviene dejarlo claro, ya que es la pregunta que más nos hacen: no limitamos el envío de webhooks entrantes. Los enviamos tan pronto como llegan, independientemente de los picos de tráfico que genere su sistema de origen; por nuestra parte, no existe ningún límite por segundo ni por minuto.

El único límite es el cupo de 30 días de su plan para la invocación de funciones. Una vez agotado dicho cupo, las llamadas posteriores dejarán de procesarse hasta que se renueve el periodo o usted actualice su plan. Más allá de eso, se aplican los límites de Shopify: Shopify Flow tiene sus propios límites de ejecución, y el tamaño máximo del payload del activador es de 50 KB.

Shopify

Se trata de los límites que impone Shopify a las API de Shopify, no los nuestros. Se aplican a lo que esta aplicación (y sus flujos de trabajo) pueden hacer en el lado de Shopify, y es posible que los alcance en una tienda de gran tamaño, incluso aunque se encuentre muy por debajo de nuestros límites.

Los matrices de entrada tienen un límite máximo de 250 elementos en todas las API de Shopify. Se rechazará cualquier solicitud que contenga una matriz con un número mayor de elementos.
La paginación se detiene a los 25 000 objetos. Los recuentos son precisos hasta 25 000; por encima de esa cifra, Shopify devuelve 25001, lo que significa «más de 25 000». Si necesita profundizar más, aplique primero un filtro.
El uso de la API de administración de GraphQL se mide en función del coste calculado de las consultas, en puntos por segundo, y el límite máximo depende del plan Shopify de la tienda:

Shopify plan	Puntos por segundo
Estándar	100
Avanzado	200
Además	1000
Enterprise (Componentes de comercio)	2000

La API de Tienda online no tiene límite de solicitudes.

Información detallada: Límites de rate de la API de Shopify