Visión general de los webhooks

Los webhooks permiten a las aplicaciones, o a los escaparates personalizados, mantenerse sincronizados con los datos de Shopery o realizar una acción después de que se produzca un evento específico. Los webhooks son una alternativa eficaz a la búsqueda continua de cambios en los datos.

Por ejemplo, un webhook puede notificar a sus sistemas internos cuando se realiza un pedido, y generar acciones de acuerdo con su lógica de negocio.

Casos prácticos

Entre los casos de uso habituales de los webhooks se incluyen los siguientes:

• Recopilación de datos para almacenes de datos
• Integración con programas de contabilidad
• Filtrado de los pedidos e información de los mismos a las empresas de transporte

Conceptos de webhook

Para orientarte con el contenido de esta guía de ayuda, vamos a dividirlo en conceptos:

Webhook: Un único mensaje de evento. Shopery puede enviar un webhook a un endpoint. Un webhook contiene una carga útil JSON en el cuerpo y algunos metadatos en las cabeceras.

Evento Webhook: Un evento controla cuándo se crean los webhooks y qué hay en la carga útil del webhook. Por ejemplo pedidos creados se envía cada vez que se crea un pedido y contiene el pedido como carga útil.

Cabeceras de webhook

Además de la carga útil del mensaje, cada mensaje webhook tiene una serie de cabeceras que contienen contexto adicional.

‍

Uso del encabezado HTTPX

X-Shopery-Secret   Nuestro increíble secreto

Probar webhooks

Puedes probar la configuración de tu webhook activándolo. Puede activar los webhooks de las siguientes maneras:

• Manualmente, utilizando la función URL de prueba mientras configura su webhook.
• Realizando la acción relacionada.

Próximos pasos

• Conozca las mejores prácticas de webhooks, incluyendo cómo responder rápidamente a webhooks, rastrear fallos, recuperar webhooks y más.
• Aprende a configurar tu aplicación para utilizar webhooks.

Mejores prácticas de Webhook

La siguiente guía describe algunas de las mejores prácticas para trabajar con webhooks.

Responder rápidamente

Después de recibir un webhook usando un endpoint HTTPS, es importante responder a la petición con un 200 OK en uno o dos segundos. Hay un tiempo de espera de cinco segundos para toda la solicitud, y el sistema de entrega webhook espera establecer la conexión en menos de un segundo o los tiempos de solicitud hacia fuera.

Optimizar la gestión de las conexiones

El sistema de entrega de webhooks utiliza HTTP Keep-Alive para reutilizar las conexiones al mismo host y endpoint. Esto reduce la congestión de la red y la latencia en las solicitudes posteriores. Asegúrese de que tiene Keep-Alive activado para su endpoint para reducir la sobrecarga de recibir peticiones concurrentes.

Prepare su endpoint para una ráfaga de peticiones

Para preparar su punto final para una ráfaga de solicitudes, desvincule el procesamiento de webhooks de las respuestas a las solicitudes. Un patrón común es almacenar la carga útil en una cola de mensajes para su posterior procesamiento por un trabajador en segundo plano. Esto reduce la posibilidad de que la solicitud se agote y que la entrega del webhook cuente como un fallo. Almacenar el webhook y responder inmediatamente asegura que tu sistema es resistente a un alto volumen de peticiones.

Gestionar los retrasos

En raras circunstancias, es posible que experimente retrasos en la recepción de webhooks. Sin embargo, los webhooks siempre se envían con los datos más recientes del recurso en cuestión. La carga útil del webhook entregado debe reflejar los atributos más recientes para el recurso entre el momento de la activación del webhook y la eventual entrega del webhook.

Si recibir webhooks con hasta un día de retraso puede causar problemas en sus sistemas, le recomendamos que compare la marca de tiempo del webhook con la fecha y hora actuales.

Fallos en las vías

Utilice las métricas de entrega para realizar un seguimiento de las entregas fallidas de webhooks y solucionarlas antes de que afecten a los usuarios.

Evitar las devoluciones

Cuando utilices el parámetro fields para especificar qué campos deben ser enviados por un webhook, incluye un campo que siempre tenga un valor único. Por ejemplo, puedes incluir el campo updated_at en el parámetro fields.

Incluir un campo que siempre tenga un valor único evita que el webhook sea descartado como duplicado, como en los casos en los que sólo se solicita el campo id.

Ignorar duplicados

Aunque la API de webhooks está diseñada para minimizar la duplicación de eventos webhook, aún es posible recibir el mismo evento más de una vez. Tu aplicación debe manejar los eventos webhook utilizando operaciones idempotentes; es decir, recibir el mismo evento webhook por segunda vez consecutiva no debería tener ningún efecto adicional. Puedes detectar eventos webhook duplicados comparando la carga útil directamente con el estado anterior.

Utilizar parámetros de filtro compatibles

La mayoría de los puntos finales de consulta admiten los parámetros de filtro created_at_min y updated_at_min. Estos filtros se pueden utilizar para crear un trabajo que recupere todos los recursos que se han creado o actualizado desde la última vez que se ejecutó el trabajo.

Construir un sistema escalable y fiable

El seguimiento del tráfico desde la plataforma de Shopery puede ser abrumador, especialmente a medida que creces.

Si necesita gestionar grandes volúmenes de notificaciones de eventos para crear un sistema escalable y fiable, puede configurar las suscripciones para enviar webhooks a Amazon EventBridge y Google Cloud Pub/Sub en lugar de a través de HTTPS.

Descripción general de la configuración de Webhooks

Shopery puede enviar eventos webhooks a través de HTTPS, más métodos vendrán en el futuro.

Requerimientos

• Está familiarizado con el funcionamiento de los webhooks
• Estás autenticado y tienes un token JWT válido
• Tienes los permisos necesarios

Flujo de configuración de webhooks

Para recibir webhooks, siga estos pasos.

• Cree un endpoint de su elección para recibir los eventos que se publiquen
• Utilice nuestra API Rest o utilice nuestra interfaz de usuario para crear un webhook que utilice el punto final como destino.

HTTPS

Este tutorial explica cómo configurar, probar y verificar endpoints webhook de tipo HTTPS.

Paso 1: Prepare su punto final

Tu endpoint debe ser una dirección webhook HTTPS con un certificado SSL válido que pueda procesar correctamente las notificaciones de eventos.

Las cargas útiles contienen JSON con los datos de los eventos webhook.

Paso 2: Crear un webhook

Puede crear su webhook utilizando la interfaz de usuario o utilizando nuestra API REST.

Creación de un webhook mediante UI

• Inicie sesión en el backoffice con un usuario con privilegios suficientes.
• Vaya a Configuración -> Webhooks
• Haga clic en Crear Webhook
• Rellene los campos con la siguiente información:
  • Nombre del webhook: Un nombre que te puede ayudar a identificar ese webhook
  • URL: Su punto final donde se enviará la carga útil
  • Eventos: Qué eventos deben activar ese webhook

Método HTTP : POST

Punto final : https://api.shopery.app/company/webhooks

Headers            : Content-Type: application/jsonAuthorization: Bearer <jwt-token>X-tenant-ID: <your-tenant-id>

‍

Nombre Tipo Descripción

name Cadena Mane del webhook

url Cadena URL de su punto final

eventos [] Lista de eventos para suscribirse

isEnabled Bool Si el webhook está activado o no

Ejemplo de carga útil

Este es un ejemplo de un cuerpo de carga útil para crear un webhook utilizando la API de Shopery:

{
  "name": "webhook test",
  "url": "https://test.com/wh",
  "events": [
    "order-created"
  ],
  "isEnabled": true
}

Respuesta API

Si la solicitud se realiza correctamente, recibirá una respuesta de la API con un campo de identificación. Esto indica que la importación ha sido aceptada y está siendo procesada.

{
  "id": "wbh_01HA4XCG60CT4G3EWF4CKYM1MF"
}

Paso 3: Probar el webhook

Puede probar el webhook utilizando la función URL de prueba en la configuración del webhook, éste intentará conectarse a su endpoint y esperará un código de estado HTTP 200.

Paso 4: Verificación del webhook

Antes de responder a un webhook, necesita verificar que el webhook fue enviado desde Shopery, puede verificar esto usando Endpoint Secret

Cada petición desde los servidores de Shopery a su endpoint contendrá esta Firma, su aplicación debe asegurarse de que la Firma enviada y la configurada en Shopery son la misma.

‍