Webhooks

ReallyQuickEmails te dispara un webhook por cada evento que ocurre durante la vida de un email: aceptación, entrega, rebote, queja, apertura, click y respuesta del destinatario.

Cómo recibir webhooks

Eventos

Payload outbound

Todos los eventos outbound (email.send, email.delivery, email.bounce, email.complaint, email.reject, email.deliverydelay, email.open, email.click) comparten la misma estructura top-level. Lo que cambia es data.

{
  "event": "email.delivery",
  "timestamp": "2026-04-29T15:30:42.123Z",
  "project_id": "uuid",
  "is_test": false,
  "environment": "staging",
  "data": { "...": "..." }
}

Campos de data

Nota: los eventos email.send y email.delivery no incluyen un campo delivered_at separado — usa event_timestamp.

Headers de la request

RQE hace POST a tu URL con:

Verificación HMAC

const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', apiKey)
  .update(rawBody)
  .digest('hex');
if (req.headers['x-rqe-signature'] !== expected) {
  return res.status(401).send('Invalid signature');
}

Importante: verifica la firma sobre el body raw, antes de cualquier parser JSON. Si el body cambia (espacios, orden de keys), el HMAC no va a coincidir.

Routing live / test / environment

Cada proyecto tiene URLs configurables:

Sin environment custom, cada evento outbound se entrega a todas las URLs configuradas (Producción y Desarrollo a la vez) — el routing no filtra por modo del envío. El header X-RQE-Environment indica el slot de cada POST (live / dev) y el flag is_test del payload te dice si el envío usó sk_test_*.

Si configuras inbound_webhook_url / inbound_webhook_url_dev, esas URLs reemplazan a webhook_url / webhook_url_dev y reciben todos los eventos (outbound + inbound) — modelo "una URL recibe todo".

Los webhooks inbound (replies) se entregan a una sola URL según el modo del envío original (ver fallback abajo). El override por environment usa inbound_webhook_environments[<key>].

Fallback automático

Aplica solo a email.inbound — los eventos outbound no tienen fallback porque van a todas las URLs configuradas. RQE usa la primera URL no vacía de esta cadena:

• Envío original con sk_test_*: inbound_webhook_url_dev → webhook_url_dev → inbound_webhook_url → webhook_url
• Envío original live: inbound_webhook_url → webhook_url → inbound_webhook_url_dev → webhook_url_dev

Si ninguna URL está configurada (outbound o inbound), el evento no se entrega.

Para environments custom, no hay fallback — si el environment declarado en el envío no está configurado, el envío entero falla con 400 ENVIRONMENT_NOT_CONFIGURED. Ver Webhook environments.

is_test en el payload

{
  "event": "email.delivery",
  "is_test": true,
  "data": { "...": "..." }
}

Como los eventos outbound llegan a todas las URLs configuradas, basta con configurar solo webhook_url para recibir todo en una sola URL — distingue el tráfico test con el flag is_test.

Inbound (replies con adjuntos)

Cuando un destinatario responde tu email, RQE captura la respuesta y la dispara como evento email.inbound.

Cuándo dispara

Solo cuando el email outbound original fue enviado vía API (POST /v1/send-email, POST /send-email o POST /v1/send-batch). En ese caso el Reply-To del email lleva un token único:

Reply-To: "Tu Empresa" <r-{token}@rqe.inbound.reallyquickemails.com>

Los clientes de email (Gmail, Outlook, Apple Mail) muestran el nombre del remitente en lugar de la dirección técnica. Cuando el destinatario responde, la respuesta se enruta automáticamente a RQE y dispara el webhook.

No dispara para envíos desde la UI de RQE (campañas, automatizaciones, "enviar prueba") — esos usan el Reply-To del sender humano para que reciba en su inbox.

Body del payload inbound

{
  "event": "email.inbound",
  "timestamp": "2026-04-28T22:45:32.299Z",
  "project_id": "uuid",
  "is_test": false,
  "data": {
    "message_id": "<gmail-message-id@mail.gmail.com>",
    "thread_id": "uuid",
    "in_reply_to": "<original-message-id@us-east-1.amazonses.com>",
    "references": ["<...>"],
    "from": { "email": "cliente@empresa.com", "name": "Cliente Externo" },
    "to": [
      { "email": "r-Rbxiu6RC@rqe.inbound.reallyquickemails.com", "name": null }
    ],
    "cc": [],
    "subject": "Re: Asunto original",
    "text_body": "respuesta plana del cliente",
    "html_body": "<div>respuesta html</div>",
    "date": "2026-04-28T23:30:49.000Z",
    "attachments": [
      {
        "filename": "factura.pdf",
        "content_type": "application/pdf",
        "size": 50826,
        "storage_key": "...",
        "download_url": "https://...?token=..."
      }
    ],
    "return_path_parsed": null,
    "original_outbound": {
      "message_id": "<original-message-id@us-east-1.amazonses.com>",
      "activity_id": "uuid",
      "campaign_id": null,
      "email_type": null,
      "thread_id": "uuid"
    }
  }
}

Igual que en los eventos outbound, el payload incluye is_test y, si el envío original usó un environment custom, también environment.

Campos clave

Límite de tamaño

150 KB total por reply (incluyendo adjuntos en MIME base64). Replies que excedan ese tamaño rebotan con "Message length exceeds limit set by recipient". Workaround: pídele al contacto que comparta archivos grandes vía link Drive/WeTransfer.

Retry y respuesta esperada

• Timeout: 10 segundos por intento.
• Intentos (eventos outbound): 5 en total — 1 inicial + 4 reintentos con backoff exponencial.
• email.inbound: un solo intento, sin reintentos.
• Idempotencia: los retries pueden re-entregar el mismo evento; si entregas a ambas URLs y solo una falla, el reintento re-entrega a las dos. Usa el par (event, data.activity_id, data.event_timestamp) para deduplicar lado-cliente.

Próximos pasos

• Tracking — qué eventos disparan webhook y cómo se generan.
• Test mode — separar tráfico dev/prod vía sk_test_*.
• Webhook environments — N URLs por proyecto vía campo environment.
• Send email — cómo disparar emails que generen estos eventos.