¿Qué son los webhooks y cómo configurarlos en Sendcloud? – Sendcloud Help Center

Ojetivo: aprende lo básico sobre webhooks y cómo configurarlos en tu panel de Sendcloud.

Para utilizar los webhooks necesitas conectarte a Sendcloud a través de una API. Para más información sobre la conexión con nuestra API, te remitimos a nuestra Documentación de la API.

Para obtener más información sobre los webhooks de Sendcloud, consulta la sección sobre webhooks de nuestra documentación sobre la API.

Para soporte de webhooks específico de la integración, revisa nuestro artículo: Mejorando la seguridad de los webhooks y el soporte de integración. Explica cómo configurar los webhooks para diferentes integraciones y las mejores prácticas para proteger tus webhooks.

¿Qué son los webhooks?

Los webhooks hacen posible que las aplicaciones se comuniquen entre ellas en "tiempo real". Otra forma de que las aplicaciones se comuniquen es a través de una API. A diferencia de una API que funciona con polling (sondeo), un webhook recibe los datos en cuanto la aplicación los gestiona. No es necesario realizar ninguna solicitud, ya que se trata de un proceso automático. Por tanto, no tienes que preocuparte por un retraso en la comunicación.

API: una API extrae periódicamente datos de la aplicación mediante una solicitud.

Webhook: un webhook no extrae datos, sino que los recibe de la aplicación en cuanto se producen.

Ejemplo: recepción de actualizaciones de seguimiento de Sendcloud

(Ver imagen más abajo como referencia)

Cuando recibes actualizaciones de seguimiento a través de la API, ocurre lo siguiente:
Tu aplicación intenta obtener datos de seguimiento de Sendcloud por intervalos. Lo hará incluso cuando no haya nuevos datos disponibles.
Cuando quieres recibir actualizaciones de seguimiento a través de un webhook, sucede lo siguiente:
Sendcloud envía las actualizaciones de seguimiento a tu aplicación tan pronto como estén disponibles en Sendcloud.

Webhooks de Sendcloud

Webhook Objeto de Integración: este webhook entra en juego cuando se añade una nueva integración API a Sendcloud. Se activa cuando se conecta, elimina o actualiza una integración API. Haz clic aquí para ver qué contiene la carga útil de este webhook.

Webhook Objeto Estado del Paquete Cambiado: este webhook se activa cuando cambia el estado de un paquete; no importa cuál sea el cambio de estado. Haz clic aquí para ver qué contiene la carga útil de este webhook.

Webhook Return Created Object: Este webhook se activa cuando se crea una devolución a través de la API o del Portal de devoluciones. Haz clic aquí para ver los detalles del payload.

¿Cómo configurar webhooks en Sendcloud?

Para que Sendcloud comunique activamente las actualizaciones de paquetes (como las actualizaciones de seguimiento), necesitas crear un endpoint API. Cada vez que se produzca una actualización, Sendcloud realizará una solicitud a través de ese endpoint. Para obtener más información, consulta la sección Webhooks de nuestra documentación API.

Copia la URL del webhook de tu aplicación
Ve a tu panel de Sendcloud y abre la configuración de tu integración API en Configuración > Integraciones > Configurar
Marca la casilla Activar comentarios de Webhook
Copia la URL de tu webhook en el campo que se muestra a continuación
Prueba tu webhook haciendo clic en el botón Test API webhook
Haz clic en Guardar

¡Listo! Tu webhook ya está configurado y la carga útil debería empezar a llegar a tu aplicación. Puedes utilizarlo para configurar desencadenantes que conduzcan a determinadas acciones. Un ejemplo sería conectar tus correos electrónicos de seguimiento a las actualizaciones de seguimiento entrantes. De esta forma podrás proporcionar actualizaciones instantáneas a tus clientes.

En el caso de los paquetes devueltos, solo recibirás actualizaciones del webhook si el envío saliente se creó a través de la tienda API.

FAQ

Si configuro un webhook, ¿a qué paquetes se aplica?

Los webhooks se configuran por integración. Esto significa que el webhook solo se aplicará a los paquetes creados a través de la integración para la que se haya configurado el webhook. Los paquetes creados mediante otras integraciones o métodos no activarán este webhook.

¿Por qué mi URL de webhook devuelve un 404 o es inaccesible?

Problema: La URL del webhook es incorrecta (por ejemplo, error tipográfico, dominio incorrecto o falta de HTTPS) o el endpoint no es accesible públicamente.

Ejemplos:

404 Not Found

DNS resolution failed

Solución: Verifica cuidadosamente la sintaxis de la URL y el dominio. Asegúrate de que el endpoint sea accesible públicamente y utilice HTTPS con un certificado SSL/TLS válido.

¿Por qué recibo errores de certificado SSL/TLS con mi webhook?

Problema: El endpoint utiliza un certificado caducado, autofirmado o mal configurado.

Ejemplos:

SSL Handshake failed

Unable to verify certificate

Solución: Instala un certificado SSL válido de una autoridad de certificación (CA) confiable, renueva los certificados caducados y verifica que los certificados intermedios estén correctamente instalados.

¿Por qué las solicitudes de mi webhook caducan o no reciben respuesta?

Problema: El servidor que recibe el webhook es demasiado lento o no responde.

Ejemplos:

 Request timed out

 Connection reset

Solución: Asegúrate de que el servidor responda dentro del límite de tiempo (timeout), optimiza el código para un procesamiento más rápido o mueve las tareas pesadas a procesos en segundo plano. También revisa posibles firewalls o limitaciones de velocidad (rate limiting).

¿Por qué mi webhook devuelve errores HTTP como 405 o 500?

Problema: El endpoint espera un método HTTP específico o no devuelve respuestas correctas.

Ejemplos:

405 Method Not Allowed

500 Internal Server Error

Solución: Asegúrate de que el endpoint acepte solicitudes POST, devuelve códigos de estado 2xx cuando se reciben correctamente y registra o maneja los errores de forma adecuada.

¿Por qué falla la autenticación o la verificación de firma de mi webhook?

Problema: El proveedor del webhook firma las solicitudes, pero el endpoint no las verifica correctamente o utiliza claves incorrectas.

Ejemplos:

401 Unauthorized

403 Forbidden

Solución: Implementa la verificación HMAC o de firma usando la clave secreta correcta y asegúrate de que los encabezados y el payload se procesen exactamente como se enviaron.

¿Por qué el payload de mi webhook es inválido o está mal formateado?

Problema: El webhook envía datos en formato JSON (u otros), pero el servidor receptor no puede procesarlos correctamente.

Ejemplos:

400 Bad Request

Unexpected token in logs

Solución: Comprueba que el Content-Type sea compatible (generalmente application/json), valida y registra el payload, y actualiza el código del endpoint para soportar nuevos campos o formatos.

¿Por qué algunas solicitudes de mi webhook están siendo limitadas o descartadas?

Problema: El endpoint recibe demasiadas solicitudes y comienza a descartarlas.

Ejemplos:

429 Too Many Requests

Requests delayed or silently failing

Solución: Añade colas o throttling para manejar picos de carga, implementa reintentos (retries) con backoff exponencial y monitoriza o escala los recursos del servidor según sea necesario.

Haz clic aquí para ir a nuestra referencia de la API de Sendcloud y ver la carga útil del webhook.