Un webhook es un aviso automático que un sistema le envía a otro cuando ocurre algo. En lugar de que su sistema pregunte cada minuto «¿llegó algún mensaje?», el proveedor le avisa en el momento en que llega.
API y webhook: la diferencia
Con una API, su sistema toma la iniciativa: pide enviar un SMS, consulta un estado, origina una llamada. Con un webhook, la iniciativa es del proveedor: le avisa a su sistema que algo pasó.
La alternativa a los webhooks es consultar una y otra vez (lo que se llama polling). Funciona, pero desperdicia recursos, llega tarde y choca con los límites de uso. Los webhooks resuelven las tres cosas.
Cómo funciona, paso a paso
- Usted le indica al proveedor una dirección HTTPS de su sistema y qué eventos le interesan.
- Cuando ocurre uno de esos eventos, el proveedor envía una solicitud a esa dirección con los datos del evento.
- Su sistema verifica la firma, procesa el evento y responde rápido con un «recibido».
Ejemplos con SMS, WhatsApp y llamadas
- Mensaje entrante: un cliente responde un SMS o un WhatsApp y su sistema lo recibe al instante para mostrarlo o actuar.
- Estado de entrega: el mensaje que envió pasó a entregado, leído o fallido; su sistema actualiza el pedido o reintenta por otro canal.
- Llamada en cola: entra una llamada y su CRM abre la ficha del cliente antes de que el agente conteste.
- Llamada perdida: alguien colgó esperando y su sistema crea una tarea para devolver la llamada.
Seguridad: cómo saber que el aviso es auténtico
Cualquiera que conozca la dirección podría enviarle datos falsos. Por eso un webhook serio va firmado:
- El proveedor calcula una firma (normalmente HMAC con SHA-256) usando un secreto que solo usted y él conocen, y la envía en un encabezado.
- La firma incluye una marca de tiempo, para rechazar avisos viejos reenviados por un atacante.
- Su sistema recalcula la firma con el mismo secreto y descarta todo aviso que no coincida.
Además, la dirección debe ser HTTPS, y el proveedor no debería aceptar direcciones internas o privadas.
Buenas prácticas al recibir webhooks
- Responda rápido. Guarde el evento y procéselo aparte; si tarda, el proveedor puede considerarlo fallido.
- Use el identificador del evento para no procesar dos veces el mismo aviso.
- No dependa del orden. Un «entregado» puede llegar antes que un «enviado».
- Registre los fallos y revise la bitácora de entregas del proveedor cuando algo no cuadra.
- Proteja el secreto como una contraseña y cámbielo si se expone.
Cuándo necesita webhooks
Si su sistema solo envía notificaciones y no le importa qué pasa después, una API basta. En cuanto necesite reaccionar (a una respuesta del cliente, a un mensaje fallido, a una llamada que entra), necesita webhooks.
La API de TelHarbor incluye webhooks firmados para mensajes entrantes, estados de entrega y eventos de llamadas, configurados por nuestro equipo. Vea también cómo enviar SMS por API.
Preguntas frecuentes
¿Un webhook es lo mismo que una API?
No. La API la llama su sistema para pedir algo; el webhook lo envía el proveedor a su sistema para avisar algo.
¿Necesito un servidor para recibir webhooks?
Necesita una dirección HTTPS pública que pueda recibir solicitudes: su propio servidor, su CRM o un servicio en la nube.
¿Qué pasa si mi sistema está caído cuando llega el aviso?
Depende del proveedor; por eso conviene revisar la bitácora de entregas y tener una forma de consultar por API lo que se perdió.
¿Los webhooks tienen costo?
En TelHarbor están incluidos en el plan de API.