Verificación de webhooks firmados
Muchos servicios firman los webhooks que envían, de modo que el destinatario pueda comprobar que una solicitud procede realmente de ellos y que no ha sido alterada durante el trayecto. Si configura la autenticación de un webhook en HMAC, la aplicación comprueba dicha firma antes de que nada llegue a Shopify Flow. Una solicitud que no supere la comprobación se rechaza con el código de error 401 y nunca se ejecuta ningún flujo de trabajo.
Hay dos formas de configurarlo: seleccione el remitente de la lista o describa cómo firma.
Proveedores integrados
Seleccione el proveedor en la sección «Proveedor de firma» y pegue su clave de firma. A continuación, la aplicación verifica que el proveedor cumpla con los requisitos de documentación - el encabezado correcto, la codificación, el contenido firmado y la ventana de reproducción - , por lo que no es necesario configurar nada más. Cada proveedor cuenta con su propia guía de configuración, desde la creación del punto final hasta la configuración del flujo de trabajo de Shopify Flow.
En cada guía se detalla exactamente qué aspectos comprueba la aplicación en relación con ese remitente y dónde se encuentra su secreto de firma.
Firma personalizada: cualquier otro remitente
Si su remitente no figura en la lista, seleccione «Firma personalizada» y describa cómo se realiza la firma. La documentación de su proveedor incluirá una línea similar a esta:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Esa única línea responde a todos los campos:
| Escenario | Según el ejemplo | Qué significa |
|---|---|---|
| Encabezado de la firma | X-Acme-Signature |
El encabezado que contiene la firma |
| Algoritmo | hmac_sha256 |
SHA-256, SHA-1 o SHA-512 |
| Codificación | hex |
hexadecimal, base64 o base64url |
| Payload firmado | {timestamp}.{body} |
El texto exacto que se firmó |
| Marca de tiempo | un encabezado como X-Acme-Timestamp |
Por dónde circula el valor de timestamp |
| Tolerancia de repetición | 300 segundos | Rechace las solicitudes anteriores a esta fecha |
The signed payload
Escriba lo que firma el remitente utilizando estos marcadores de posición:
| Marca de posición | Se convierte en |
|---|---|
{body} |
El cuerpo de la solicitud sin procesar, byte a byte. Obligatorio. |
{timestamp} |
La marca de tiempo del encabezado o del encabezado de la firma |
{url} |
La URL de este webhook, tal y como la introdujo en el remitente |
{header:name} |
El valor de otro encabezado de solicitud |
Formatos habituales: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Utilice la opción «Empezar desde un proveedor» para copiar un formato similar y modifique únicamente lo que difiera.
Dónde se coloca la firma
- Sin formato: el valor del encabezado es la firma, opcionalmente seguida de un prefijo que usted elija, como
sha256=ov1,. - Clave = valor: el encabezado contiene pares del tipo
t=1700000000,v1=abc.... Indique el nombre de la clave que contiene la firma (v1), opcionalmente el de la clave que contiene la marca de tiempo (t), y si los pares van separados por,o;.
Si un encabezado contiene varias firmas separadas por espacios - algo que hacen algunos remitentes cuando se renueva un secreto - , se acepta cualquiera de ellas que coincida.
El secreto
Por lo general, debe pegar el secreto tal y como lo muestra el remitente. Algunos remitentes proporcionan una clave codificada en Base64 con un prefijo, como whsec_...: seleccione la opción «codificada en Base64» e introduzca el prefijo que desea eliminar.
Pruebas antes de la puesta en marcha
El comprobador de firmas se encuentra debajo de los ajustes y funciona con los cambios no guardados.
- Pegue el cuerpo y los encabezados de una solicitud real y pulse «Verificar». Se le mostrarán todos los pasos - encabezado encontrado, firma leída, marca de tiempo dentro del rango, payload generado, firmas comparadas - y el texto exacto que se ha firmado, de modo que, en caso de discrepancia, se le indicará dónde se ha producido el error, en lugar de mostrarse simplemente un «firma no válida».
- Al generar un ejemplo válido, se obtienen encabezados firmados correctamente y un archivo
curllisto para ejecutarse con su configuración actual. Si se acepta dicha solicitud, su configuración es coherente de principio a fin.
El probador nunca inicia un flujo de trabajo, no registra nada en el historial y no se contabiliza en su plan.
La firma no coincide. ¿Qué debería comprobar?▾
En este pedido: el secreto (la causa más habitual, como un espacio de más o una clave de entorno incorrecta), la payload firmada (la ausencia de . o : entre la marca de tiempo y el cuerpo), la codificación (hexadecimal frente a base64) y si algo entre el remitente y la aplicación ha modificado el cuerpo. Las firmas abarcan los bytes sin procesar, por lo que un proxy que reformatee el JSON las invalida.
Las solicitudes fallan con el mensaje «marca de tiempo fuera de los límites de tolerancia»▾
El reloj del remitente no está sincronizado, la solicitud se retrasó o se volvió a intentar con una marca de tiempo obsoleta, o bien la unidad de la marca de tiempo es incorrecta. Compruebe si su remitente utiliza segundos, milisegundos o una fecha ISO.
Mi remitente necesita primero un proceso de verificación▾
Algunos servicios (Zoom, Dropbox, Asana, Trello, Notion) envían una solicitud de verificación a la que el punto final debe responder antes de que estos servicios transmitan cualquier evento, cada uno a su manera. Por este motivo, no se ofrecen como proveedores de configuración con un solo clic. Póngase en contacto con el soporte indicando el nombre de su remitente si necesita utilizar alguno de ellos.
¿Se guarda la firma en algún sitio?▾
No. Los encabezados de firma se ocultan en el Historial y en el Inspector de solicitudes en tiempo real, ya que una firma puede reproducirse dentro de su ventana de tolerancia.