Soluciona problemas con los webhooks

Normalmente, ocurre un evento, SendPulse envía una solicitud POST a la URL de tu webhook en unos segundos, tu servidor devuelve un código de éxito y la solicitud aparece en el registro con un estado verde. Si falla alguno de estos pasos, el registro muestra cuál.

Hablemos de cómo solucionar problemas con los webhooks, desde un servidor que no recibe solicitudes hasta una firma que no coincide.

Índice

Tu servidor no recibe solicitudes

SendPulse no envió la solicitud o tu servidor no la aceptó. El registro de solicitudes muestra cuál de las dos situaciones ocurrió.

Para encontrar la causa, ve a Configuración de la cuenta > Webhooks y busca el webhook. Su tarjeta debe mostrar el estado Activo. Si muestra Inactivo, haz clic en los tres puntos de la tarjeta y selecciona Activar.

Haz clic en los tres puntos y selecciona Editar. Después, haz clic en Solicitud de prueba. Un punto verde con el código 200 significa que tu URL es accesible. Si la prueba falla, consulta La solicitud de prueba falla.

Repite la acción que activa el evento.

Haz clic en los tres puntos y selecciona Registro. Después, haz clic en Actualizar registros.

Si no hay ningún registro, consulta Ocurrió un evento, pero no hay un registro.

Si el registro muestra un error, consulta la sección correspondiente a su estado: Tiempo de espera agotado, 4xx o 5xx.

Si el registro muestra 200, pero tu servidor no procesó los datos, la solicitud llegó al servidor. Busca el error en tu controlador y en los registros de tu servidor.

Ocurrió un evento, pero no hay un registro

SendPulse no envió una solicitud. Esto puede ocurrir por los siguientes motivos:

El evento no está seleccionado en el webhook o está seleccionado en otra herramienta, como Entregado en SMS en lugar de Correo electrónico.
El webhook está inactivo.
La acción no activa este evento. Por ejemplo, desactivar un suscriptor en una lista de correo no equivale a cancelar su suscripción, por lo que SendPulse no envía el evento Suscriptor dado de baja.
Era una solicitud de prueba y las solicitudes de prueba no aparecen en el registro.
Es un evento de chatbot o ventana emergente que la sección Webhooks no envía. Consulta Los eventos de chatbots y ventanas emergentes no aparecen en la lista.

Para solucionarlo, haz clic en los tres puntos de la tarjeta del webhook y selecciona Editar. En la lista Eventos, asegúrate de que el evento esté seleccionado en la herramienta correcta. Asegúrate de que la opción Estado esté activada y haz clic en Guardar.

Compara tu acción con la descripción del evento en Elige los eventos que quieres recibir. Repite la acción, abre el registro y haz clic en Actualizar registros. El registro aparece en unos segundos.

Si sigue sin aparecer ningún registro, contacta al servicio de atención al cliente e indica la URL del webhook, el evento y la hora de la acción.

El registro muestra el estado Tiempo de espera agotado

SendPulse no recibió una respuesta de tu servidor a tiempo. La columna Tiempo de respuesta muestra un guion.

Para solucionarlo, abre el registro y expande la entrada. La sección Cuerpo de la solicitud muestra lo que envió SendPulse. Asegúrate de que tu servidor sea accesible desde internet mediante HTTPS y de que su certificado sea válido.

Si tu servidor tiene un firewall, permite las direcciones IP de la lista Direcciones IP de origen del webhook del formulario del webhook.

Si tu controlador tarda mucho en procesar los datos, devuelve primero un código de éxito y procesa los datos en segundo plano.

Haz clic en Reintentar en la fila del registro y después en Actualizar registros.

El registro muestra un estado 4xx

Tu servidor recibió la solicitud y la rechazó. Las causas habituales son las siguientes:

Una ruta de URL incorrecta (404).
Un controlador que no acepta solicitudes POST (405).
Una autorización requerida (401, 403).
Un framework que bloquea las solicitudes POST sin un token CSRF (403).
Un límite en la cantidad de solicitudes (429).

Para solucionarlo, expande la entrada en el registro. La sección Cuerpo de la respuesta muestra la respuesta de tu servidor.

Para 404, verifica la ruta del campo URL del webhook.

Para 405, configura tu controlador para que acepte solicitudes POST.

Para 401 o 403, añade el encabezado de autorización que espera tu servidor en la sección Encabezados adicionales o excluye la ruta del webhook de las verificaciones de autorización y CSRF.

Para 429, permite más solicitudes desde las direcciones de la lista Direcciones IP de origen del webhook.

Haz clic en Reintentar en la fila del registro y después en Actualizar registros.

El registro muestra un estado 5xx

Tu servidor recibió la solicitud, pero se produjo un error al procesarla. SendPulse reintenta la solicitud automáticamente después de 1, 5 y 30 minutos. Cada intento aparece como un registro independiente con su número en la columna Intento, y el cuerpo de la solicitud y la firma permanecen iguales.

Para solucionarlo, expande la entrada en el registro. La sección Cuerpo de la respuesta muestra el error de tu servidor y la sección Cuerpo de la solicitud muestra lo que envió SendPulse.

Busca el error en los registros de tu servidor utilizando la hora de la columna Fecha y hora. El registro muestra la hora en la zona horaria de tu cuenta.

Asegúrate de que tu controlador acepte el cuerpo de cada evento seleccionado: el conjunto de campos de data varía según el evento.

Una vez que corrijas el error, espera el reintento automático o haz clic en Reintentar en la fila del registro y después en Actualizar registros.

La solicitud de prueba falla

El resultado de una solicitud de prueba aparece junto al botón Solicitud de prueba: un punto, el código de estado y el tiempo de respuesta, por ejemplo, 405 · 87 ms.

Las causas son las mismas que para las solicitudes normales, con una diferencia adicional. La solicitud de prueba tiene el tipo de evento test, no incluye el campo scope y tiene un campo data vacío, por lo que un controlador que espera datos del evento puede fallar al procesarla.

Para solucionarlo, guarda el webhook, haz clic en los tres puntos de su tarjeta, selecciona Editar y haz clic en Solicitud de prueba.

Si el resultado no es 200, consulta Tiempo de espera agotado, 4xx o 5xx.

Si tu servidor falla únicamente con la solicitud de prueba, configura el controlador para que acepte un cuerpo sin scope y con un campo data vacío.

Vuelve a hacer clic en Solicitud de prueba.

SendPulse no acepta la URL del webhook

SendPulse solo admite URL HTTPS públicas y cada webhook de tu cuenta necesita su propia URL. Los mensajes de validación del campo URL del webhook son los siguientes:

Mensaje	Causa	Qué hacer
Introduce una URL HTTPS válida	La URL comienza con `http://` o no es una dirección válida.	Introduce una URL que comience con `https://`.
Introduce una URL HTTPS pública válida	La URL apunta a `localhost`, un dominio interno o una dirección IP privada, o el dominio no se resuelve en una dirección IP.	Utiliza una dirección accesible desde internet. Si tu servidor aún está en desarrollo, utiliza un túnel o un servicio que te proporcione una URL HTTPS pública.
Ya existe un webhook con esta URL	Otro webhook de tu cuenta utiliza esta URL.	Haz clic en Filtrar, introduce la URL en el campo Buscar y haz clic en Aplicar. Después, haz clic en los tres puntos del webhook encontrado, selecciona Editar y añade los eventos.

Una vez que cambies la URL, haz clic en Guardar y después en Solicitud de prueba para verificarla.

SendPulse no acepta un encabezado adicional

Los encabezados adicionales tienen límites y algunos nombres están reservados porque SendPulse los establece por su cuenta. Los mensajes de validación del encabezado son los siguientes:

Mensaje	Causa	Qué hacer
Este encabezado está reservado y no se puede sobrescribir	SendPulse establece este encabezado por su cuenta, por ejemplo, `Content-Type`, `X-Signature` o `X-Event-Type`.	Utiliza otro nombre de encabezado.
Introduce un nombre de encabezado válido con entre 1 y 128 caracteres permitidos	El nombre está vacío, tiene más de 128 caracteres o contiene caracteres no permitidos en los nombres de encabezados HTTP, como espacios.	Introduce un nombre con entre 1 y 128 caracteres permitidos.
Introduce un valor de encabezado con entre 1 y 1024 caracteres ASCII imprimibles	El valor está vacío, tiene más de 1024 caracteres o contiene caracteres que no son ASCII, como letras no latinas.	Introduce un valor con entre 1 y 1024 caracteres ASCII imprimibles.

Si el botón Añadir encabezado está inactivo, el webhook ya tiene el máximo de 10 encabezados. En conjunto, los encabezados de un webhook pueden ocupar hasta 8 KB.

Una vez que cambies los encabezados, haz clic en Guardar, después en Solicitud de prueba y verifica en tu servidor que se haya recibido el encabezado.

La firma no coincide con el encabezado X-Signature

Tu servidor calcula el hash HMAC-SHA256 sobre un cuerpo diferente o con una clave diferente. Las causas habituales son las siguientes:

Una clave regenerada que no se actualizó en el servidor.
Un cuerpo que se analizó y se serializó de nuevo antes de la verificación.
Una comparación sin el prefijo sha256=.
Una clave utilizada como bytes decodificados en lugar de una cadena de texto.

Para solucionarlo, haz clic en los tres puntos de la tarjeta del webhook y selecciona Editar. En el campo Clave secreta, haz clic en el ícono del ojo y después en el ícono de copiar, y compara la clave con la de tu servidor. Cuando regeneras la clave, la anterior deja de funcionar inmediatamente.

Calcula el hash sobre el cuerpo de la solicitud sin procesar, antes de analizar el JSON.

Compara el resultado con el valor completo del encabezado, incluido sha256=, o elimina el prefijo antes de comparar.

Utiliza la clave exactamente como aparece en el campo, como una cadena de texto.

Haz clic en Solicitud de prueba y verifica la firma de la solicitud de prueba.

El mismo evento llega más de una vez

Esto puede ocurrir por los siguientes motivos:

Un reintento automático: tu servidor respondió con un error o demasiado tarde, por lo que SendPulse volvió a enviar la misma solicitud.
Un reintento manual desde el registro de solicitudes.
Los eventos Etiqueta vinculada y Etiqueta desvinculada ocurren en pares: una solicitud para el suscriptor y otra para la lista de correo. No se trata de un duplicado; el campo entity_type del cuerpo de la solicitud permite distinguir las dos solicitudes.

Para solucionarlo, devuelve un código de éxito de inmediato, antes de procesar los datos.

Antes del procesamiento, verifica si tu servidor ya gestionó este evento. Los eventos de SMS contienen el campo event_id para este propósito.

Para los eventos de etiquetas, verifica el campo entity_type.

Los eventos llegan fuera de orden

SendPulse envía cada evento como una solicitud independiente y las solicitudes pueden llegar fuera de orden. Por ejemplo, Correo abierto puede llegar antes que Entregado.

Para gestionar esta situación, ordena los eventos por el campo occurred_at del cuerpo de la solicitud, no por la hora en que tu servidor los recibió.

Tu controlador dejó de procesar eventos después de la migración

SendPulse migra automáticamente los webhooks del servicio de correo electrónico y SMTP de la antigua sección API y webhooks a la sección Webhooks, y desactiva los registros anteriores.

Las solicitudes de un webhook migrado también contienen los datos en el formato anterior, en el elemento "0". Sin embargo, un webhook migrado envía un evento por solicitud en lugar de un arreglo de eventos.

El cuerpo de la solicitud es un objeto JSON que contiene el elemento "0" y los campos user_id, scope, event_type, occurred_at y data. Un controlador que procesa el cuerpo de la solicitud como un arreglo podría fallar al procesar estas solicitudes.

Para solucionarlo, ve a Configuración de la cuenta > Webhooks, busca el webhook migrado por su URL, haz clic en los tres puntos de su tarjeta, selecciona Editar y verifica la URL y los eventos.

Actualiza tu controlador para que lea un evento del cuerpo de la solicitud en lugar de recorrer un arreglo. Para conservar tu código de procesamiento actual, lee el evento del elemento "0". Realiza una acción que active uno de los eventos seleccionados y después verifica el estado del nuevo registro en el registro de solicitudes.

No utilices una solicitud de prueba para esta comprobación porque no contiene el elemento "0".

Faltan solicitudes antiguas en el registro

SendPulse almacena los registros durante 30 días y el registro de un webhook eliminado no está disponible. La página muestra 20 registros a la vez.

Para ver registros anteriores de los últimos 30 días, haz clic en Mostrar más. Los registros de más de 30 días y los registros de webhooks eliminados no se pueden restaurar, así que, si necesitas el historial, almacena las solicitudes en tu sistema.

Para pausar un webhook y conservar su registro, haz clic en los tres puntos de su tarjeta y selecciona Desactivar en lugar de Eliminar.

Un miembro del equipo no ve la sección Webhooks

Un miembro del equipo solo ve la sección Webhooks si su rol de usuario tiene el permiso Configuración en el grupo Correo electrónico y campañas de marketing.

Para solucionarlo, pídele al propietario de la cuenta que te asigne un rol de usuario personalizado con este permiso. Actualiza la página y ve a Configuración de la cuenta > Webhooks.

Leer también: Cómo crear un rol de usuario personalizado.

Los eventos de chatbots y pop-ups no aparecen en la lista

La lista Eventos del formulario del webhook no incluye eventos de chatbots ni de ventanas emergentes. Los webhooks de chatbots y ventanas emergentes se configuran en los ajustes del chatbot o de la ventana emergente correspondiente.

Para recibir estos eventos, configura un webhook para chatbots y ventanas emergentes.

Leer también: Enviar webhook en el elemento Acción, Configura las notificaciones sobre nuevos clientes potenciales utilizando webhooks.

Si el problema persiste, contacta al servicio de atención al cliente e indica la URL del webhook, el evento y la fecha y hora de la solicitud que aparecen en el registro.

Para seguir utilizando webhooks, aprende a configurar webhooks, verificar la firma de la solicitud y consultar el registro de solicitudes y reintentar solicitudes.