Referencia de webhooks

¿Quieres alertas por email, Slack o Discord? Sigue la guía de notificaciones.

Los datos

Cada mensaje nuevo activa un POST HTTP a tu URL con un Content-Type: application/json body:

{
  "id": "d8f2e71a20b4",
  "event": "message.created",
  "project": {
    "id": "prj_8f2k1q",
    "name": "acme-site"
  },
  "source": {
    "type": "form",
    "name": "Website contact form"
  },
  "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
  "reply": {
    "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
    "method": "open_conversation"
  },
  "message": {
    "id": "msg_4t9s2e",
    "from": {
      "name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "subject": "Question about pricing",
    "body": "Hi, quick question about the Pro plan...",
    "receivedAt": "2026-07-14T09:30:00.000Z"
  }
}

Campos

• event: message.created para un mensaje entrante o notification.test para el botón Probar. Los eventos de prueba tienen un valor null en message y source.
• project: el proyecto cuya bandeja recibió el mensaje (su id y name).
• source: de dónde viene el mensaje. type es "form" (el endpoint del formulario) o "email" (el dirección de email de proyecto); name es la etiqueta del origen en tu bandeja.
• message.from: el del remitente email (siempre presente) y name (puede estar vacío si el remitente no lo ha indicado).
• message.subject: opcional en los envíos de formularios, por lo que puede estar vacío.
• message.receivedAt: fecha y hora ISO 8601, UTC.
• reply.url: abre esta conversación en Mailcontact, donde su propietario puede responder tras iniciar sesión. El enlace no concede acceso por sí solo. Los eventos de prueba tienen un valor null en reply.

Entrega

• Responde rápido. Devuelve 2xx al aceptar los datos y procesa el trabajo de forma asíncrona. La entrega agota el tiempo de espera a los 10 segundos.
• Al menos una vez. Una respuesta lenta o un fallo temporal puede entregar el mismo mensaje varias veces. Evita duplicados con el id, también enviado en el Idempotency-Key y X-Mailcontact-Event-Id cabeceras.
• Los fallos temporales y HTTP 429 se reintentan hasta cinco veces con retraso exponencial. La mayoría de otros 4xx detienen la entrega.
• Usa HTTPS público por el puerto 443. Se rechazan redes privadas, credenciales en URL y redirecciones.

Seguridad

Los datos aún no llevan firma: cualquiera que descubra tu URL puede enviar datos falsos. Toma estas precauciones:

• Usa una ruta de webhook larga e impredecible y no la publiques.
• Trata los datos como no fiables y valídalos antes de actuar.
• No ejecutes acciones destructivas o irreversibles desde un webhook sin firma. Notificar, registrar y poner en cola son usos adecuados; eliminar datos no.

Los webhooks aún no llevan firma. Recibir datos no prueba quién los envió.

Webhooks y canales de notificación

Utiliza el guía de notificaciones para alertas por email, Slack y Discord. Esta referencia cubre el formato de webhook genérico para tu código. Consulta precios para las ofertas actuales.