Cómo conectar los webhooks estándar a Shopify Flow
«Standard Webhooks» es una especificación abierta para la firma de webhooks, utilizada por OpenAI, Supabase Auth Hooks y una lista cada vez mayor de servicios. Un único ajuste preestablecido los cubre todos. «Workflow Webhooks» convierte esa llamada en un activador de «Shopify Flow», de modo que su tienda pueda reaccionar ante ella: etiquetar a un cliente, añadir una nota al pedido, enviar un correo electrónico interno, actualizar un metacampo… cualquier cosa que pueda hacer Shopify Flow.
Esta guía describe todo el proceso - Standard Webhooks envía, Workflow Webhooks recibe y verifica, Shopify Flow actúa - , con la firma HMAC de Standard Webhooks comprobada en cada solicitud, de modo que únicamente Standard Webhooks pueda iniciar su flujo de trabajo.
Lo que puede construir
- Tome un webhook de OpenAI - un trabajo por lotes finalizado o una respuesta completada - y haga que Shopify Flow actúe en función del resultado en su tienda.
- Reaccione ante un hook de autenticación de Supabase, de modo que, al registrarse en su propia aplicación, se asigne el cliente correspondiente de Shopify.
- Reciba notificaciones de cualquier servicio que cumpla con la especificación de standardwebhooks.com sin necesidad de configurar una firma personalizada.
Eventos típicos que se pueden enviar: cualquier evento que defina el servicio de envío.
Este mismo ajuste preestablecido también verifica los webhooks de OpenAI y los Auth Hooks de Supabase.
Antes de empezar
- Workflow Webhooks instalado en su tienda de Shopify.
- Shopify Flow instalada, que se puede descargar de forma gratuita desde la App Store de Shopify.
- Una cuenta de Standard Webhooks con permiso para crear webhooks.
Paso 1: Cree el webhook en Workflow Webhooks
- Acceda a Workflow Webhooks -> Webhooks -> Crear webhook y asígnele un nombre que pueda reconocer en Shopify Flow, como por ejemplo
Standard Webhooks events. - En «Autenticación», seleccione HMAC.
- En «Proveedor de firma», seleccione «Webhooks estándar». La aplicación rellena automáticamente el encabezado, el algoritmo, el payload firmado y la ventana de repetición; no hay que configurar nada más.
- Deje el campo «Secreto» en blanco por ahora y haga clic en «Guardar». Copie la URL del webhook que aparece en la página.
Consulte Autenticación para conocer los demás modos de autenticación, y Asignación de la carga útil y variables de flujo para seleccionar qué campos se envían a Shopify Flow.
Paso 2: Añada el punto final en «Webhooks estándar»
Añada la URL como punto final en el servicio de envío y, a continuación, copie el secreto de firma que se le muestra (comienza por whsec_).
Cómo encontrar su secreto de firma de Webhooks estándar
El secreto de firma que comienza por «whsec_». Péguelo tal cual; si aparece como «v1,whsec_...» (Supabase), omita el «v1,» inicial.
La propia documentación de Standard Webhooks sobre las firmas de los webhooks, disponible en, incluye el texto exacto y las capturas de pantalla correspondientes a su cuenta.
Pegue esa clave secreta en el campo «Secret» del webhook en Workflow Webhooks y guarde los cambios. A partir de ese momento, cada entrega de los webhooks estándar se verificará antes de llegar a Shopify Flow.
Qué comprueba esto
| ¿Qué? | Valor |
|---|---|
| Encabezado de la firma | webhook-signature |
| Dónde se coloca la firma | El valor del encabezado, tras el prefijo v1, |
| ¿Qué se ha firmado? | {header:webhook-id}.{timestamp}.{body} |
| Firma | HMAC-SHA256, codificado en base64 |
| Marca de tiempo | El encabezado webhook-timestamp, expresado en segundos de Unix |
| Protección contra la reproducción | Se rechazan las solicitudes cuya marca de tiempo firmada se sitúe a más de 5 minutos del momento actual. |
| El secreto | Se decodifica en Base64 antes de su uso. El prefijo whsec_ se elimina antes de la decodificación. Péguelo exactamente tal y como lo muestra el remitente. |
En la carga útil firmada, {body} es el cuerpo de la solicitud sin procesar, byte a byte; {timestamp} es la marca de tiempo mencionada anteriormente; y {header:webhook-id} es el encabezado de la solicitud webhook-id.
Cualquier solicitud que incumpla alguno de estos requisitos se rechaza con el error 401, se registra en Historial y resolución de problemas y nunca inicia un flujo de trabajo.
Paso 3: Crear el flujo de trabajo Shopify Flow
- En «Shopify Flow», cree un flujo de trabajo y seleccione el activador «Workflow Webhooks».
- Haga clic en «Grabar eventos» y, a continuación, envíe un evento de prueba desde «Webhooks estándar» (o utilice la opción «Enviar prueba» en Workflow Webhooks) para que Shopify Flow aprenda la estructura de sus datos.
- Cada webhook del que disponga activa el mismo activador de Shopify Flow, por lo que debe añadir una primera condición basada en el identificador del webhook para que este flujo de trabajo se limite únicamente a los webhooks estándar. El identificador aparece en la página del webhook.
- Añada sus acciones: etiquete a un cliente, añada una nota, envíe un correo electrónico interno o actualice un metacampo.
Paso 4: Realice una prueba de extremo a extremo
Activador de un evento real en «Standard Webhooks». En «Workflow Webhooks» -> «History» debería ver la invocación con el estado «Success». Si la firma era incorrecta, aparecerá en su lugar una entrada con el estado «Failed» y el motivo correspondiente; en Verificación de webhooks firmados se explica cómo funciona el verificador de firmas, que le muestra exactamente en qué paso se produjo el error.
La firma no coincide▾
En este pedido: el secreto (la causa más habitual: un espacio de más o una clave del entorno incorrecto), si el remitente está utilizando el secreto de otro punto final y si hay algún elemento entre los webhooks estándar y la aplicación que reescriba el cuerpo. Las firmas abarcan los bytes sin procesar, por lo que un proxy que reformatee el JSON las invalida. El verificador de firmas de la página de webhooks muestra el texto exacto que se firmó.
Me aparece el error 401 en todas las solicitudes▾
Compruebe que la autenticación del webhook esté configurada en HMAC con el proveedor «Standard Webhooks» seleccionado, que se haya introducido el secreto y que «Standard Webhooks» esté enviando la solicitud a la URL exactamente tal y como la muestra la aplicación, incluido el código al final.
No aparece nada en el historial▾
La solicitud nunca llegó. Vuelva a comprobar la URL en «Standard Webhooks» y consulte el registro de entrega de «Standard Webhooks» para ver la respuesta que recibió. Un error 404 indica que el webhook es incorrecto o ha sido eliminado; un error 429 significa que ha superado el límite de invocaciones de su plan; consulte Planes y uso.
El flujo de trabajo se ejecuta para eventos incorrectos▾
Cada webhook de su tienda activa el mismo activador de Shopify Flow. Añada una condición basada en el ID del webhook como primer paso del flujo de trabajo, o limite los eventos que envía desde los webhooks estándar.
Las solicitudes fallan con el mensaje «marca de tiempo fuera de los límites de tolerancia»▾
Standard Webhooks incluye una marca de tiempo y la aplicación rechaza cualquier evento con más de 5 minutos de antigüedad. Normalmente, esto se debe a un problema de sincronización por parte del remitente o a que Standard Webhooks ha vuelto a intentar el envío mucho más tarde con la marca de tiempo original. Los reintentos de la misma solicitud original no pueden pasar; solicite a Standard Webhooks que envíe un evento nuevo.
Relacionado
- Verificación de webhooks firmados - todos los proveedores que verificamos, y cómo describir a aquellos que no verificamos.
- Asignación de la carga útil y variables de flujo - extraer los campos adecuados del payload y introducirlos en Shopify Flow.
- Protección contra entregas duplicadas - ¿Qué ocurre cuando los webhooks estándar vuelven a intentar una entrega?
- Historial y resolución de problemas - el registro de todas las solicitudes, con la posibilidad de reproducirlas.