¿Y quién me avisa? Qué es un webhook, explicado para tesoreros

Hace pocos años casi nadie en una tesorería decía "webhook". Hoy aparece en cada conversación sobre cobranza, comercio electrónico o conexión con el banco. Y cuando lo menciono frente a un cliente, no es raro que me miren como diciendo "¿de qué me estás hablando?". Es normal: es un término que viene del mundo de los sistemas y llegó a las finanzas casi sin presentarse.

Este explicador es para quien está en ese lugar. Mi tesis: un webhook es un aviso automático. En lugar de que tu sistema pregunte una y otra vez "¿ya pasó?", el otro sistema te avisa en el momento en que pasa. Con esa idea se entiende por qué importa para cobrar, conciliar y saber al momento qué tiene la empresa.

Qué es un webhook, sin tecnicismos

Un webhook es un mensaje que un sistema le manda a otro, por internet, en cuanto ocurre algo que al segundo le interesa. Ese "algo" se llama evento: un pago aprobado, un depósito recibido, una transferencia rechazada.

Funciona en dos tiempos. Primero, tu empresa le da al proveedor (el banco, la pasarela de pagos, la plataforma de cobranza) una dirección web propia y le dice qué eventos quiere recibir. Después, cada vez que uno de esos eventos ocurre, el proveedor manda un mensaje a esa dirección con los datos: qué pasó, cuándo, por cuánto y con qué referencia. Nadie tuvo que preguntar.

¿Y qué tiene que ver con las APIs?

Todo. En el explicador sobre APIs vimos que una API es tu sistema haciéndole una pregunta o una petición al banco, y el banco contestando. El webhook es la misma conversación en sentido contrario: quien habla primero es el banco o la pasarela, y tu sistema escucha.

En la práctica no compiten: se usan juntas. El webhook avisa que algo pasó; la API sirve para confirmar el detalle o pedir lo que falte. La guía de webhooks de Stripe, por ejemplo, sugiere usar su API para recuperar cualquier dato que no haya llegado en el aviso.

Qué trae un aviso

Un webhook es, casi siempre, un mensaje corto en formato JSON, el mismo empaque de campos con nombre que usan las APIs. Este es un ejemplo ilustrativo de un aviso de depósito:

{
  "evento": "deposito.recibido",
  "id_evento": "evt_20261121_000731",
  "fecha": "2026-11-21T23:47:05-06:00",
  "monto": 58000.00,
  "moneda": "MXN",
  "referencia": "FAC-10458",
  "cuenta": "0123456789"
}

Ejemplo ilustrativo, no corresponde a la especificación de ningún proveedor.

Además de los datos, un buen aviso trae dos cosas que no se ven en el ejemplo. Una firma, que permite comprobar que el mensaje lo mandó de verdad el proveedor y que nadie lo modificó en el camino. Y un acuse: tu sistema contesta "recibido" y, si no contesta, el proveedor lo vuelve a intentar.

El comercio electrónico lo volvió cotidiano

El término se volvió del diario por las tiendas en línea. Cuando alguien compra a las 23:47, la tienda necesita saber si el pago se aprobó para liberar el pedido, mandar el correo de confirmación y descontar el inventario. Y muchas veces la respuesta no llega en el mismo segundo: el banco del cliente confirma después, el pago en efectivo en una tienda de conveniencia se hace horas más tarde, una transferencia llega cuando el cliente la manda.

Por eso las pasarelas de pago trabajan con webhooks. La documentación de Stripe lo describe así: sirven para reaccionar a eventos que no ocurren al instante, como cuando el banco de un cliente confirma un pago o cuando un cliente disputa un cargo. En México, pasarelas como Mercado Pago también documentan sus notificaciones por webhook. Sin ese aviso, la tienda tendría que preguntar por cada pedido pendiente, todo el tiempo.

Cobranza: el depósito que se aplica solo

Aquí es donde el webhook deja de ser tema de sistemas y se vuelve tema de tesorería. En cobranza, el evento que importa es "me pagaron". Si el aviso llega al ERP con el monto y la referencia, el sistema puede buscar la factura, aplicar el pago y liberar el crédito del cliente sin que nadie capture nada.

Pero el webhook no hace magia: solo entrega lo que el pago trae. Si el depósito llega sin referencia, o con una referencia que no corresponde a ninguna factura, el aviso llega igual de rápido, pero lo que llega es una partida por identificar. Por eso insisto en que sin referencia no hay automatización: el webhook acelera lo que ya está bien diseñado.

Lo mismo pasa con los cobros recurrentes. En las APIs de domiciliación que publican algunas fintech en México hay avisos para cada etapa: cuando el cliente autoriza el cargo y cuando el cargo se cobra o se rechaza, con su motivo. Son las piezas que permiten que una cobranza recurrente se concilie sola.

Tesorería: enterarse cuando pasa, no al día siguiente

Para la tesorería, el valor del webhook es el tiempo. Sin avisos, la empresa se entera de lo que pasó cuando llega el estado de cuenta o cuando alguien entra al portal. Con avisos, se entera en el momento. Los eventos que más le sirven a una tesorería suelen ser estos, según lo que ofrezca cada banco o plataforma:

• Depósito recibido: para aplicar la cobranza y actualizar la posición de caja.
• Pago liquidado: para cerrar la cuenta por pagar sin llamar al banco.
• Pago rechazado o devuelto: para corregir la cuenta del proveedor y volver a pagar el mismo día, no una semana después.
• Cambio de estatus de un cobro recurrente: autorizado, cobrado o rechazado.

Hay otra razón para prestarle atención. En el explicador de APIs escribí que un agente de IA necesita datos confiables y servicios que pueda consumir. Los webhooks son la tercera pieza: son lo que le dice al agente que algo pasó y que es momento de actuar, en lugar de tenerlo revisando todo cada cinco minutos. Es la base de lo que describí en la tesorería agéntica.

Lo que hay que cuidar

Un webhook es muy útil, pero no es infalible. Quien lo integra tiene que diseñar para cuatro situaciones que la propia documentación de los proveedores reconoce:

1. Que no llegue. Si tu sistema está caído, el aviso no entra. Los buenos proveedores reintentan: Stripe, por ejemplo, reintenta la entrega hasta por tres días. Aun así, conviene una conciliación de respaldo contra el estado de cuenta.
2. Que llegue dos veces. Stripe advierte que un mismo evento puede recibirse más de una vez. Si tu sistema no lo detecta por su identificador, puede aplicar el mismo pago dos veces.
3. Que llegue en desorden. El aviso de "cobrado" puede llegar antes que el de "autorizado". Stripe no garantiza el orden de entrega, y la documentación de dLocal para domiciliación en México dice que el aviso del mandato y el del pago son independientes y pueden llegar en cualquier orden.
4. Que no sea lo que parece. Un aviso puede ser falso si nadie verifica la firma. Y no todo aviso es dinero en la cuenta: en la documentación de tapi, el aviso de un débito por cobrar indica que hay una factura por debitar, y la respuesta de recibido solo acusa recepción; no confirma el cobro.

Tres preguntas para tu banco o tu pasarela

1. ¿Qué eventos notifican por webhook (depósitos, pagos liquidados, rechazos, devoluciones, cobros recurrentes) y qué datos trae cada aviso, en especial la referencia?
2. ¿Cómo firman los avisos y cuántas veces y durante cuánto tiempo reintentan si mi sistema no responde?
3. ¿El aviso confirma dinero liquidado o solo un cambio de estatus, y con qué consulta por API lo confirmo?