Recibir eventos en vivo con webhooks

Hasta ahora, en las integraciones por API, tu sistema le hablaba a arrobaMail: vos pedías el token, dabas de alta un contacto, enviabas. Los webhooks de eventos invierten esa dirección: ahora arrobaMail le habla a tu sistema. Cada vez que pasa algo —una campaña terminó de enviarse, alguien abrió, un correo rebotó, alguien se dio de baja—, arrobaMail le manda un aviso a un servidor tuyo, en el momento.

Es la pieza que te permite tener tus propios datos siempre frescos: auditar, sincronizar tu base, o disparar tu lógica de negocio en respuesta a lo que hace tu audiencia. Mirá el sentido del flujo:

1. Qué son los webhooks de eventos

Un webhook es, en simple, una llamada que un sistema le hace a otro cuando ocurre algo. En este caso, configurás una URL de tu servidor en arrobaMail y, a partir de ahí, arrobaMail le hace un POST HTTP a esa URL cada vez que sucede un evento, con los datos de lo que pasó. No tenés que andar preguntando "¿abrió?, ¿abrió?": arrobaMail te avisa solo.

Ojo, no confundir con el nodo Webhook de una automatización. Ese (que vimos en transaccionales) dispara un POST cuando un contacto pasa por un punto de un flujo. Los webhooks de eventos de esta guía son distintos: te notifican de los eventos de email (aperturas, rebotes…) a medida que ocurren.

2. Para qué te sirven

Recibir los eventos en vivo te habilita a:

• Auditar y reportar con tus propios tableros, sin entrar a la plataforma.
• Sincronizar tu base de datos: marcar en tu CRM quién abrió, quién rebotó, quién se dio de baja —y mantener tu estado al día—.
• Accionar: disparar lógica de negocio cuando algo pasa (por ejemplo, si un cliente importante hace clic en tu oferta, avisarle al equipo de ventas).

3. Configurá tu URL

Desde la configuración de tu cuenta, pegás la URL pública de tu servidor que va a recibir los avisos. Tiene que ser HTTPS (no se aceptan URLs sin cifrar). Algo como:

https://tu-servidor.com/webhooks/arrobamail

Esa URL es el "buzón" donde arrobaMail va a dejar cada evento.

4. Los eventos que vas a recibir

arrobaMail te notifica de los eventos del ciclo de vida de tus envíos. Los principales:

• campaign.sent — una campaña terminó su envío.
• contact.open — un contacto abrió un correo.
• contact.click — un contacto hizo clic en un enlace.
• contact.bounce — un correo rebotó (con su tipo: temporal o permanente).
• contact.complaint — alguien marcó tu correo como spam.
• contact.unsubscribe — alguien se dio de baja.
• automation.triggered — un contacto entró en un flujo de automatización.

Cada POST trae los datos del evento (el contacto, la campaña, el momento). La estructura exacta del payload conviene confirmarla en tus primeras pruebas (lo vemos en el paso 6).

5. Programá el receptor

Tu servidor tiene que escuchar ese POST, leer el JSON, ejecutar tu lógica y responder HTTP 200 para que arrobaMail sepa que lo recibiste. Un receptor mínimo en PHP:

<?php // webhooks/arrobamail
$payload = json_decode(file_get_contents("php://input"), true);

$event = $payload["event"]   ?? null;   // ej: contact.bounce
$email = $payload["email"]   ?? null;

switch ($event) {
    case "contact.bounce":
        // marcá el email como rebotado en tu base
        break;
    case "contact.unsubscribe":
        // dalo de baja también en tu CRM
        break;
    // ...otros eventos que te interesen
}

http_response_code(200);
echo json_encode(["status" => "ok"]);

La idea es siempre la misma en cualquier lenguaje: leer el body, mirar el tipo de evento, hacer lo tuyo, responder 200.

6. Probá y depurá

Antes de confiar en tu lógica, mirá qué llega de verdad:

• Logueá el payload completo en las primeras pruebas. Así ves exactamente qué campos manda arrobaMail para cada evento, en vez de adivinarlos.
• Usá el historial de eventos de tu cuenta (en Herramientas) para ver el registro de lo que se envió y cruzarlo con lo que tu servidor recibió. Es la herramienta principal para debuggear la integración.

7. Buenas prácticas

• Respondé rápido. Tu receptor debe contestar 200 enseguida. Si tenés trabajo pesado, encolalo y procesalo aparte; no hagas esperar al webhook.
• Hacelo idempotente. Puede llegar el mismo evento más de una vez. Diseñá tu lógica para que recibir dos veces "rebotó" no rompa nada (por ejemplo, marcando por ID de evento).
• Verificá el origen. Aceptá solo lo que venga a tu URL secreta (y, si querés más seguridad, validá el contenido antes de actuar).
• No dependas solo del webhook para datos críticos. Para reportes exactos, complementá con consultas a la API (los webhooks son para reaccionar en vivo; la API, para la verdad consolidada).

Errores frecuentes a evitar

• URL sin HTTPS. No se acepta. Tu endpoint tiene que ser cifrado.
• No responder 200. Si tu servidor no confirma, arrobaMail puede considerar el envío fallido.
• Asumir el formato del payload. Logueá primero, programá después. Los campos los confirmás viendo lo que llega.
• Procesar pesado dentro del webhook. Encolá el trabajo y respondé rápido, o vas a tener timeouts.

Próximos pasos

1. Repasá el panorama de todas las formas de integrar en conectar arrobaMail con tus sistemas.
2. Combinalos con envíos desde tu sistema en enviar emails transaccionales.
3. Mirá la API completa en API REST v3 y su referencia.