Webhooks de SMS
Los webhooks de SMS envían un POST a tu servidor cuando un mensaje se envía, se entrega, falla o llega. Esta guía te muestra la forma rápida de registrarlo desde Private Integrations, la regla del HTTP 200 que decide si se guarda, y el método por API.
La forma sencilla: configúralo en el portal
No necesitas llamar a la API para registrar un webhook. Se puede configurar desde el portal en menos de un minuto.
- Inicia sesión en tu Zonitel Office Portal.
- En el menú lateral izquierdo, expande Settings y haz clic en Private Integrations.
- Abre la pestaña Webhooks.
- En SMS webhook, pega tu Webhook URL.
- Haz clic en Save.
La URL debe ser válida y responder con HTTP 200 para guardarse: si no responde correctamente no se almacena, así que ten tu endpoint activo antes de guardar. Para quitar el webhook más adelante, borra el campo y guarda de nuevo.
El resto de este artículo cubre cómo hacer lo mismo por la API, que es lo que necesitas si aprovisionas cuentas de forma programática.
Advanced: método y autenticación del receptor
- Abre Advanced debajo de la URL del webhook y activa Use a custom method or authentication.
- Elige el HTTP method y la Authentication que requiere el servicio receptor. Métodos: POST, PUT, PATCH o GET. Autenticación: None, Bearer token, API key, Basic (user + password) o Custom header.
- Completa los campos de la opción elegida y guarda el webhook. La URL receptora debe responder con HTTP 200 para que el portal la acepte.
El valor predeterminado es POST sin autenticación. GET no lleva cuerpo: el evento viaja como parámetros de consulta. Para API key, elige dónde enviarla e introduce el nombre del encabezado o parámetro que exige el receptor.
Las credenciales opcionales del receptor pertenecen al servicio que recibe el webhook. Son distintas del token de la API de Zonitel y de X-Client-Id, que tu software utiliza para llamar a nuestra API. Proporciona únicamente credenciales destinadas a ese receptor.
El ejemplo de registro por API que aparece abajo configura la URL. Utiliza el portal para las opciones Advanced mostradas aquí.
Cómo Funciona
-
Registra una URL de webhook en tu cuenta.
-
Cada vez que se envíe, entregue, falle un SMS o se reciba un mensaje entrante, Zonitel enviará una solicitud POST a tu URL de webhook.
-
Tu servidor debe responder con HTTP 200 OK dentro de 5 segundos para confirmar la recepción.
Importante: Las solicitudes utilizan Bearer Authentication. Incluye tu token de acceso en el header
Authorization.
Registrar un Webhook
Endpoint:
Cuerpo de la solicitud (JSON):
Notas:
-
La URL debe ser HTTPS y accesible públicamente.
-
Tu servidor debe responder dentro de 5 segundos con HTTP 200 OK.
Ejemplo de respuesta exitosa:
Consultar Webhook Registrado
Endpoint:
Ejemplo de respuesta:
Elimina el webhook de SMS registrado
Usa DELETE en la misma ruta para dejar de enviar eventos de SMS a tu receptor. La eliminación correcta devuelve HTTP 204.
curl --request DELETE \
--url https://api.zonitel.com/api/v3/integrations/sms/webhooks \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Client-Id: YOUR_CLIENT_ID'Notificaciones de Webhook
Notificación de SMS entrante
Notificación de estado de mensaje (saliente)
Respuestas Comunes de Error
-
401 Unauthorized
-
403 Forbidden
-
400 Bad Request
-
500 Internal Server Error
Buenas Prácticas
-
Usa siempre HTTPS para tus URLs de webhook.
-
Responde con HTTP 200 OK dentro de 5 segundos.
-
Mantén tu token Bearer seguro y nunca lo compartas públicamente.
-
Revisa periódicamente que tus webhooks estén funcionando correctamente.
Para ir más lejos
Recibir eventos es la mitad de una integración de mensajería. Enviar SMS y MMS, consultar un mensaje, revisar la capacidad restante y programar campañas masivas se explican en Envía y recibe SMS con la API.
¿Necesitas ayuda?
Llamada/Texto/WhatsApp: (833) 966-4835
Email: info@zonitel.com