Configurar webhooks

Published: 16 de julio de 2026 · Last updated: 21 de julio de 2026 · By Marcus Biel

Los webhooks permiten que Maildroppa notifique a otra aplicación cuando ocurre algo importante en tu cuenta.

En lugar de preguntar repetidamente a Maildroppa si se creó, actualizó, dio de baja o etiquetó a un suscriptor, tu aplicación puede recibir una solicitud HTTPS poco después de que ocurra el evento.

La página Webhooks es el lugar central para esta integración de toda la cuenta. Puedes crear varios endpoints, elegir los eventos que recibe cada endpoint, añadir encabezados de autenticación, probar la conexión, inspeccionar intentos de entrega y repetir un evento de producción cuando sea necesario.

Cómo funcionan los webhooks de cuenta

Un webhook de cuenta sigue este proceso:

1. Se produce un evento en Maildroppa, como la creación de un suscriptor.
2. Maildroppa encuentra cada endpoint activo suscrito a ese evento.
3. Maildroppa crea una entrega para cada endpoint coincidente.
4. El payload JSON se firma con el Signing secret de webhooks de tu cuenta.
5. Maildroppa envía una solicitud HTTPS POST a la URL del endpoint guardada.
6. Tu endpoint verifica la firma, almacena o procesa el evento y devuelve una respuesta HTTP.
7. Maildroppa registra el resultado en Delivery history y vuelve a intentar automáticamente los fallos temporales.

Si varios endpoints se suscriben al mismo evento, cada endpoint recibe su propia entrega. El evento de negocio tiene el mismo Event ID para todos, mientras que cada entrega tiene su propio Delivery ID.

Los webhooks de cuenta son diferentes de un paso «Send a webhook» dentro de una Automation. Los webhooks de cuenta escuchan eventos de cuenta seleccionados en Maildroppa. Un webhook de Automation se envía solo cuando un suscriptor llega a ese paso concreto. Ambos utilizan el Signing secret de webhooks de la cuenta, por lo que rotar el secreto afecta a cada receptor de webhook saliente que verifica firmas de Maildroppa.

Abrir la página Webhooks

Abre «Settings», expande «Developers» y selecciona «Webhooks».

La página contiene tres áreas principales:

• Signing secret
• Endpoints
• Delivery history del endpoint seleccionado

Cuando tengas más de un endpoint, selecciona una fila de endpoint para mostrar su Delivery history. Si no has seleccionado uno explícitamente, Maildroppa muestra el historial del primer endpoint de la lista.

Antes de crear un endpoint

Prepara un receptor en tu servidor antes de configurar Maildroppa. El receptor debe:

• Estar disponible mediante una URL HTTPS pública.
• Aceptar solicitudes POST con un cuerpo application/json.
• Conservar el cuerpo de la solicitud sin procesar hasta que se haya verificado la firma de Maildroppa.
• Devolver un estado 2xx solo después de que el evento se haya aceptado de forma segura.
• Procesar entregas repetidas de forma idempotente mediante el Event ID.
• Responder rápidamente en lugar de realizar trabajo lento durante la solicitud.

Un patrón fiable consiste en verificar la solicitud, almacenar el Event ID y el payload en una cola o base de datos duradera, devolver 200 o 204 y procesar la acción de negocio después.

No expongas un equipo de desarrollo, una dirección de red local ni un script sin protección como receptor de webhook de producción. Maildroppa acepta únicamente destinos HTTPS públicos y vuelve a comprobar el destino cuando se envía una entrega.

Paso 1: Generar el Signing secret

Cada solicitud de webhook de Maildroppa está firmada. Tu receptor utiliza el Signing secret para verificar que la solicitud fue creada por Maildroppa y que el cuerpo no se modificó durante el tránsito.

En la parte superior de la página, el panel Signing secret muestra uno de estos estados:

• Missing — Aún no existe ningún Signing secret.
• Ready — Hay un Signing secret configurado.
• Loading — Maildroppa está recuperando el estado actual.

Haz clic en «Generate secret» cuando el estado sea Missing.

Maildroppa muestra el nuevo secreto inmediatamente. Comienza con whsec_. Haz clic en «Copy» y guárdalo en el gestor de secretos o en la configuración protegida del entorno que utiliza tu receptor.

El valor completo se muestra solo inmediatamente después de generarlo o rotarlo. Cuando recargas o abandonas la página, Maildroppa muestra únicamente que existe un secreto y cuándo se actualizó por última vez. No vuelve a revelar el secreto almacenado.

Si pierdes el secreto

Si el receptor ya no tiene el secreto actual, haz clic en «Rotate secret» y guarda el valor recién mostrado.

La rotación sustituye el secreto anterior inmediatamente. Maildroppa no conserva ambos valores durante un período de transición. Actualiza cada receptor que use este secreto de cuenta antes de enviar más pruebas o depender de las entregas de producción.

Las nuevas entregas, los reintentos programados, las pruebas y las repeticiones se firman con el secreto actual en el momento de la solicitud HTTP. Esto significa que una entrega creada antes de la rotación aún puede firmarse con el nuevo secreto cuando se intente posteriormente.

Trata el secreto como una contraseña

No incluyas el Signing secret en código de navegador, un repositorio público, una URL, una página de error ni un registro normal de la aplicación.

Solo el receptor del lado del servidor necesita el secreto. Si crees que se ha expuesto, rótalo y actualiza todos los receptores inmediatamente.

Verificar una firma de webhook

Cada solicitud contiene estos encabezados de Maildroppa:

• X-Maildroppa-Event-Id — Identifica el evento de negocio.
• X-Maildroppa-Delivery-Id — Identifica esta entrega concreta.
• X-Maildroppa-Timestamp — La hora de firma como segundos Unix.
• X-Maildroppa-Signature — La firma HMAC versionada.

Maildroppa también envía:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

La firma tiene este formato:

v1=<lowercase hexadecimal HMAC>

Maildroppa la crea con HMAC-SHA256. El contenido firmado es la marca de tiempo, seguida de un punto y seguida del cuerpo de solicitud JSON sin procesar exacto:

<timestamp>.<raw request body>

Utiliza el Signing secret como clave HMAC.

El siguiente ejemplo de Node.js muestra el paso de verificación esencial. rawBody debe ser los bytes originales de la solicitud, no JSON que ya se haya analizado y vuelto a serializar.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Después de verificar la firma, compara también la marca de tiempo con la hora de tu servidor. Rechaza solicitudes fuera de una tolerancia corta elegida para tu infraestructura, como cinco minutos. Esto reduce el riesgo de que una solicitud válida capturada se repita mucho más tarde.

Analiza y procesa el JSON solo después de que ambas comprobaciones hayan pasado.

Causas comunes de errores de firma

Una firma suele fallar por una de estas razones:

• El receptor utiliza un secreto antiguo después de una rotación.
• Un middleware analizó o modificó el JSON antes de calcular la firma.
• El receptor firma solo el cuerpo y omite <timestamp>..
• La marca de tiempo se trata como una fecha con formato en lugar del valor exacto del encabezado.
• El prefijo v1= se omite de la comparación.
• El HMAC calculado se codifica de forma diferente en lugar de hexadecimal en minúsculas.

Registra el Event ID y el Delivery ID cuando falle la verificación, pero nunca registres el Signing secret ni valores sensibles de encabezados personalizados.

Paso 2: Añadir un endpoint

Haz clic en «Add endpoint» en la sección Endpoints.

El editor contiene cuatro partes:

• URL del endpoint
• Eventos
• Encabezados personalizados
• Estado Active

Los nuevos endpoints comienzan como Active, y todos los eventos mostrados en el editor están seleccionados inicialmente. Revisa la selección antes de guardar para que el receptor reciba solo las notificaciones que realmente necesita.

Configurar la URL del endpoint

Introduce la URL pública completa que debe recibir las solicitudes de Maildroppa, por ejemplo:

https://integrations.example.com/webhooks/maildroppa

La URL debe cumplir estos requisitos:

• Debe utilizar https://.
• Debe contener un nombre de host público válido.
• Puede tener hasta 2.048 caracteres.
• No puede contener variables de plantilla con { o }.
• No puede contener un nombre de usuario ni una contraseña antes del nombre de host.
• No puede contener un fragmento de URL que comience con #.
• Debe utilizar el puerto HTTPS estándar 443.
• No puede utilizar localhost, una dirección IP sin procesar ni un nombre de host que se resuelva en una red privada o reservada bloqueada.

Se admiten parámetros de consulta, pero no incluyas claves de API ni otros secretos en la URL. Las URL son visibles en la lista de endpoints y en los datos de entrega. Usa un Custom header para las credenciales en su lugar.

Maildroppa no sigue redirecciones. Guarda el destino HTTPS final en lugar de una URL que devuelva 301, 302, 307 o 308.

El nombre de host de destino se resuelve de nuevo antes del envío. Se rechaza un nombre de host que posteriormente se resuelva en una dirección privada o bloqueada aunque fuera válido cuando se guardó el endpoint.

Elegir eventos

Selecciona al menos un evento. Un endpoint recibe únicamente los tipos de evento seleccionados en su editor.

La página ofrece estas opciones de evento:

Suscriptor creado — subscriber.created

Se envía cuando se crea un suscriptor en la cuenta de Maildroppa.

Utiliza este evento para crear el contacto correspondiente en un CRM, una plataforma de datos de clientes, una base de datos interna u otro sistema consciente de permisos.

No interpretes este evento como prueba de que cada registro ha completado Double Opt-in. El estado del suscriptor en el payload describe el estado actual.

Suscriptor actualizado — subscriber.updated

Se envía cuando cambia la información integrada del suscriptor o los valores de campos personalizados.

Utiliza el objeto completo del suscriptor en el payload como la representación actual de Maildroppa. Evita suponer que solo cambió una propiedad concreta.

Las asignaciones y eliminaciones de etiquetas tienen sus propios tipos de evento para que se puedan gestionar por separado.

Suscriptor dado de baja — subscriber.unsubscribed

Se envía cuando el suscriptor pasa al estado de baja mediante una acción de cancelación de suscripción.

Utiliza este evento para suprimir el contacto en sistemas conectados. No vuelvas a suscribir automáticamente a la persona porque otro sistema siga marcando el contacto como activo.

Etiqueta añadida — subscriber.tag_added

Se envía cuando se asigna una etiqueta a un suscriptor.

El payload contiene el suscriptor y la etiqueta implicados en este cambio concreto.

Etiqueta eliminada — subscriber.tag_removed

Se envía cuando se elimina una etiqueta de un suscriptor.

El payload contiene el suscriptor actualizado y la etiqueta eliminada. La etiqueta eliminada se proporciona por separado aunque ya no esté presente en la matriz tags actual del suscriptor.

Formulario enviado — form.submitted

Se envía cuando un visitante envía un formulario de registro de Maildroppa.

Trata esto como una señal de envío de formulario, no como una confirmación de que se ha completado Double Opt-in. Cualquier flujo de trabajo que requiera una suscripción confirmada debe seguir respetando el estado actual del suscriptor y el proceso de confirmación.

Usa endpoints separados cuando las responsabilidades sean distintas

Puedes enviar eventos diferentes a sistemas diferentes. Por ejemplo:

• Envía eventos de suscriptores y etiquetas a un CRM.
• Envía eventos de baja a un servicio de supresión.
• Envía eventos de envío de formularios a un flujo de análisis.

Los endpoints separados reducen el tráfico innecesario y facilitan el diagnóstico de fallos. Cada endpoint tiene su propia selección de eventos, URL, encabezados personalizados, estado activo, pruebas y Delivery history.

Añadir encabezados personalizados

Los encabezados personalizados son opcionales. Úsalos cuando el receptor requiera una clave de API, un token bearer, un identificador de inquilino u otro encabezado fijo.

Haz clic en «Add header» y, a continuación, introduce el Header name y el Header value. Algunos ejemplos adecuados son:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Puedes añadir hasta 20 encabezados personalizados.

Los nombres de encabezado:

• Son obligatorios.
• Pueden contener hasta 128 caracteres.
• Deben utilizar caracteres válidos para nombres de encabezados HTTP.
• Deben ser únicos sin tener en cuenta mayúsculas ni minúsculas.

Los valores de encabezado:

• Son obligatorios.
• Pueden contener hasta 2.000 caracteres.
• No pueden contener saltos de línea.

Los siguientes nombres están reservados y no pueden sustituirse mediante un encabezado personalizado:

• Content-Type
• Content-Length
• Host
• User-Agent
• Cualquier nombre que comience por X-Maildroppa-

Esto evita que un valor personalizado sustituya los encabezados de entrega y firma de Maildroppa.

Cómo se almacenan los secretos de los encabezados

Maildroppa cifra los valores de encabezados personalizados antes de almacenarlos. Los valores guardados no se devuelven al navegador de forma legible.

Cuando edites el endpoint más adelante, el campo de valor mostrará «Stored value kept». Déjalo vacío cuando el secreto existente deba permanecer sin cambios. Introduce un valor nuevo para sustituirlo.

Si cambias el nombre del encabezado, vuelve a introducir el valor. Maildroppa conserva un secreto almacenado únicamente mientras su nombre de encabezado original permanezca sin cambios.

Eliminar una fila de encabezado elimina ese encabezado de futuras entregas después de guardar el endpoint.

Los valores de encabezados personalizados se tratan como sensibles en la información de solicitudes almacenada. Se enmascaran en lugar de mostrarse en Delivery history.

Activar o desactivar el endpoint

Deja seleccionado «Active» cuando el endpoint esté listo para recibir eventos inmediatamente.

Desmárcalo cuando quieras guardar la configuración sin iniciar entregas. Puedes activar el endpoint más adelante desde la lista de endpoints.

Un endpoint inactivo:

• No recibe eventos que ocurran posteriormente.
• No puede enviar un Test webhook.
• Permanece visible y editable.
• Mantiene disponible su Delivery history existente.

Activar un endpoint no rellena eventos que ocurrieron mientras estuvo inactivo.

Haz clic en «Save» cuando la URL, la selección de eventos, los encabezados y el estado sean correctos.

Comprender la lista de endpoints

Cada fila de endpoint muestra:

• La URL de destino.
• Una insignia Active o Inactive.
• Los tipos de evento suscritos.
• El número de encabezados personalizados.
• La hora en la que el endpoint se actualizó por última vez.

Las acciones disponibles son:

• On/Off — Activa o desactiva el endpoint.
• Test — Envía una solicitud de prueba inmediata a un endpoint activo.
• Edit — Cambia la URL, los eventos, los encabezados o el estado activo.
• Delete — Elimina permanentemente la configuración del endpoint tras la confirmación.

Selecciona la parte principal de una fila para abrir el Delivery history de ese endpoint debajo de la lista.

Cómo afectan los cambios guardados a las entregas existentes

Un evento de cuenta crea una entrega con una instantánea de la URL del endpoint, el payload y los encabezados personalizados de ese momento.

Editar la URL o los encabezados personalizados afecta a las entregas creadas posteriormente. Una entrega que ya estaba en cola conserva su destino original y la configuración de encabezados almacenada.

Cambiar los eventos seleccionados también afecta solo a los eventos que ocurran después. Maildroppa no crea entregas retroactivamente para tipos de evento que no estaban seleccionados cuando ocurrió el evento.

El Signing secret es distinto: se lee cuando se prepara la solicitud HTTP. Por lo tanto, una entrega pendiente o repetición puede utilizar un Signing secret recién rotado incluso si su payload y su instantánea de endpoint se crearon antes.

Probar un endpoint

Haz clic en «Test» en un endpoint activo después de que el receptor y el Signing secret estén listos.

Maildroppa envía inmediatamente una solicitud firmada utilizando la URL del endpoint guardada y los encabezados personalizados guardados. Los cambios sin guardar en un editor abierto no forman parte de la prueba.

El payload de prueba utiliza el tipo de evento webhook.test y establece livemode en false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Los ID y la marca de tiempo generados son diferentes en cada prueba real.

Una prueba realiza exactamente un intento HTTP. Las entregas de prueba no se incluyen en el programa de reintentos de producción y no se pueden repetir.

Después de que termine la solicitud, el panel de resultados muestra:

• Test success o Test failed
• Event ID
• Estado HTTP, cuando se recibió una respuesta
• Duración
• Delivery ID
• Información de error, cuando esté disponible
• Un extracto de respuesta, cuando el receptor devolvió un cuerpo

La prueba también aparece en Delivery history con una insignia Test. Utiliza el filtro «Test» para mostrar solo solicitudes de prueba.

Comprender el payload de producción

Los eventos de cuenta de producción utilizan una envoltura JSON común:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Las propiedades de nivel superior significan:

• id — El Event ID. Coincide con X-Maildroppa-Event-Id.
• type — La clave de evento seleccionada en el editor del endpoint.
• schema_version — La versión del esquema del payload. Úsala al decidir cómo analizar el evento.
• created_at — La hora en que se creó el payload de evento, en UTC.
• livemode — true para eventos de producción y false para eventos de prueba.
• data — El contenido específico del evento.

Enruta los eventos mediante el valor type exacto. Ignora las propiedades adicionales que tu integración no necesite para que las adiciones de payload compatibles no rompan el receptor.

Payload de evento de suscriptor

Los eventos de suscriptor contienen la representación actual del suscriptor dentro de data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields y tags son matrices. Pueden estar vacías. Una propiedad de suscriptor también puede ser null cuando no existe ningún valor, por lo que tu receptor debe seguir el esquema del payload en lugar de asumir que está presente cada valor de perfil opcional.

Payload de evento de etiqueta

Los eventos de etiqueta contienen tanto el suscriptor como la etiqueta que causó el evento:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Para subscriber.tag_removed, data.tag sigue identificando la etiqueta eliminada aunque la matriz tags actual del suscriptor ya no la contenga.

IDs de evento, IDs de entrega e idempotencia

El Event ID y el Delivery ID tienen propósitos diferentes.

Event ID

El Event ID identifica el evento de negocio. Aparece en:

• La propiedad id de nivel superior del payload.
• El encabezado de solicitud X-Maildroppa-Event-Id.
• Delivery history.

El mismo evento puede enviarse a varios endpoints suscritos. Esas entregas comparten el Event ID.

Los reintentos y las repeticiones manuales también conservan el Event ID original. Almacena los Event ID procesados y haz que la acción de negocio sea idempotente para que una solicitud repetida no cree contactos duplicados, repita una acción irreversible ni aplique el mismo cambio dos veces.

Delivery ID

El Delivery ID identifica un registro de entrega. Aparece en:

• El encabezado de solicitud X-Maildroppa-Delivery-Id.
• Delivery history.

Cada entrega de endpoint tiene su propio Delivery ID. Una repetición manual crea un Delivery ID nuevo y conserva el Event ID original.

Utiliza el Delivery ID para el seguimiento técnico y la asistencia. Utiliza el Event ID para la deduplicación a nivel de negocio.

Devolver la respuesta HTTP correcta

Maildroppa clasifica las respuestas de la siguiente forma:

• Cualquier respuesta 2xx marca la entrega como correcta.
• Las respuestas 408 Request Timeout, 429 Too Many Requests y 5xx son fallos temporales y pueden volver a intentarse.
• Los fallos de red que pueden ser temporales se vuelven a intentar.
• Las redirecciones y otras respuestas 3xx no se siguen y se tratan como fallos terminales.
• Otras respuestas 4xx se tratan como fallos terminales y no se vuelven a intentar.

Devuelve 200, 202 o 204 solo cuando el evento se haya aceptado de forma segura. Si el procesamiento lleva tiempo, almacena primero el evento y devuelve una respuesta correcta antes de realizar el trabajo más lento de forma asíncrona.

No devuelvas una redirección a otra URL de webhook. Configura la URL final en Maildroppa en su lugar.

Programa de reintentos automáticos

Las entregas de producción pueden realizar hasta siete intentos HTTP.

Después de un fallo reintentable, Maildroppa programa el siguiente intento con estos retrasos:

1. Después del intento 1: 1 minuto
2. Después del intento 2: 5 minutos
3. Después del intento 3: 30 minutos
4. Después del intento 4: 2 horas
5. Después del intento 5: 12 horas
6. Después del intento 6: 24 horas

Si el intento 7 sigue recibiendo un fallo reintentable, la entrega pasa a Dead y no se programa ningún otro intento automático.

El programa se mide desde cada intento fallido individual. La hora de entrega real puede ser ligeramente posterior porque las entregas se procesan de forma asíncrona y también están sujetas a límites de protección del sistema.

Soluciona un problema temporal del receptor antes de la hora «Next retry» mostrada siempre que sea posible. Si los intentos automáticos han terminado, utiliza Replay después de que el receptor vuelva a estar en buen estado.

Comprender Delivery history

Delivery history pertenece al endpoint seleccionado actualmente. La URL del endpoint aparece en el encabezado de sección para que puedas confirmar qué historial estás viendo.

Utiliza estos filtros:

• All — Muestra entregas de producción y de prueba.
• Production — Muestra solo entregas de eventos en vivo.
• Test — Muestra solo pruebas manuales.

Haz clic en «Refresh» para recuperar el estado más reciente. No es necesario dejar el historial abierto mientras Maildroppa envía o vuelve a intentar una entrega.

La página muestra las 50 entregas coincidentes más recientes para el filtro seleccionado.

Columnas de entrega

Cada fila contiene:

• Created — Cuándo se creó el registro de entrega.
• State — Pending, Success, Failed o Dead.
• HTTP — Estado de respuesta, número de intentos, duración y la próxima hora de reintento cuando corresponda.
• Subscriber — El correo electrónico del suscriptor cuando el evento está conectado a un suscriptor.
• Delivery — Tipo de evento, Event ID y Delivery ID.
• Actions — Replay cuando la entrega es apta.

Si no se realizó ninguna solicitud HTTP, la columna HTTP muestra «No HTTP attempt». Esto puede suceder cuando Maildroppa rechaza la solicitud antes de enviarla, por ejemplo, porque falta el Signing secret o el destino guardado ya no se puede utilizar de forma segura.

Cuando está disponible, la fila también muestra un Error y un extracto de Response devuelto por el receptor. No devuelvas secretos ni datos personales sensibles en el cuerpo de respuesta de un webhook porque parte de esa respuesta puede aparecer en el registro de entregas de la cuenta.

Estados de entrega

Pending significa que la entrega está esperando su primer intento o un reintento programado. «Next retry» aparece cuando se ha programado otro intento.

Success significa que el receptor devolvió una respuesta 2xx. No se requiere ningún otro intento automático.

Failed significa que la entrega terminó con un problema no reintentable, se rechazó antes de un intento HTTP o se detuvo antes de que pudiera enviarse.

Dead significa que se utilizaron todos los intentos automáticos para un problema reintentable sin recibir una respuesta correcta.

Retención del historial

Los registros de entrega se conservan durante un tiempo limitado:

• Entregas de producción correctas: 30 días
• Entregas de producción fallidas: 90 días
• Entregas de producción Dead: 90 días
• Entregas de prueba: 30 días

Mantén tus propios registros de integración cuando necesites un historial de auditoría más largo. Almacena Event ID y Delivery ID, pero evita almacenar secretos innecesariamente.

Repetir una entrega

Haz clic en «Replay» cuando se deba intentar de nuevo una entrega de producción completada.

Replay está disponible para entregas de producción en estado Success, Failed o Dead. No está disponible mientras una entrega está Pending, y las entregas de prueba no se pueden repetir.

Una repetición:

• Crea una nueva entrega Pending.
• Crea un nuevo Delivery ID.
• Conserva el Event ID original.
• Conserva el tipo de evento original y el payload JSON.
• Utiliza la URL de destino guardada original y la instantánea de encabezados personalizados.
• Utiliza el Signing secret actual cuando se prepara la nueva solicitud.

Replay no reconstruye el payload a partir de los datos actuales del suscriptor. Vuelve a enviar la instantánea del evento original. Esto hace que la repetición sea auditable y evita que un evento histórico cambie silenciosamente de significado.

Solo una repetición de la misma entrega de origen puede estar Pending a la vez. Espera a que termine esa repetición antes de solicitar otra.

Asegúrate de que el endpoint esté Active antes de repetir. Si el endpoint está inactivo, la repetición en cola no se puede entregar correctamente.

Como un receptor puede haber completado la acción de negocio incluso cuando Maildroppa no recibió su respuesta correcta, repetir puede producir una solicitud duplicada. La deduplicación mediante Event ID protege al sistema conectado de repetir la acción.

Editar un endpoint

Haz clic en «Edit» para cambiar la URL, la selección de eventos, los encabezados personalizados o el estado activo.

Antes de guardar:

1. Confirma que la nueva URL ya está disponible.
2. Deja vacíos los valores de encabezado almacenados cuando deban permanecer sin cambios.
3. Introduce un valor nuevo para cada encabezado cuyo nombre se haya cambiado.
4. Revisa la selección de eventos para que las notificaciones necesarias no se eliminen por accidente.
5. Guarda y envía un nuevo Test webhook.

Recuerda que las entregas en cola conservan su URL existente y la instantánea de encabezados personalizados. Prueba la nueva configuración para futuras entregas en lugar de suponer que cambia una solicitud en cola más antigua.

Desactivar un endpoint

Utiliza el interruptor On/Off cuando quieras pausar una integración sin eliminar su configuración ni historial.

Cuando un endpoint se pone en Off:

• Los nuevos eventos ya no se ponen en cola para él.
• Las entregas Pending que todavía no se hayan reclamado para el envío se marcan como Failed.
• Test se desactiva.
• El endpoint sigue disponible para editarse y activarse más adelante.

Una solicitud que ya esté en curso en el momento de la desactivación aún puede terminar. Consulta Delivery history después de poner el endpoint en Off si esta distinción es importante para tu integración.

Los eventos omitidos mientras el endpoint está inactivo no se rellenan cuando vuelves a ponerlo en On.

Eliminar un endpoint

Haz clic en «Delete» y confirma la advertencia cuando el endpoint ya no deba existir.

Eliminar quita el endpoint de la página, detiene futuras entregas de eventos y hace fallar las entregas pendientes que todavía no se hayan reclamado para el envío.

Delete no es una forma de pausar temporalmente. Usa el interruptor On/Off cuando puedas necesitar de nuevo la configuración o su historial visible.

Antes de la eliminación, registra los Event ID o Delivery ID que todavía necesites para la auditoría de tu integración.

Solución de problemas

El endpoint no se puede guardar

Comprueba que:

• La URL comienza con https://.
• La URL utiliza un nombre de host público y el puerto 443.
• La URL no contiene variables, información de inicio de sesión ni fragmentos.
• Hay al menos un evento seleccionado.
• Cada Custom header tiene un nombre único y un valor.
• No se utilizan encabezados reservados de Maildroppa y HTTP como nombres personalizados.

Test está desactivado

Test solo está disponible para un endpoint Active. Pon el endpoint en On o edítalo y selecciona «Active»; después, guarda antes de probar.

Test no muestra ningún intento HTTP

Genera un Signing secret si el estado es Missing. Comprueba también si el nombre de host de destino es público y todavía se resuelve correctamente.

Una solicitud puede rechazarse antes del envío cuando su secreto, URL, encabezados personalizados o comprobación de seguridad de destino no son válidos.

El receptor devuelve 401 o 403

Comprueba el nombre y la credencial del Custom header guardado. Edita el endpoint e introduce de nuevo el valor si ha cambiado.

Verifica también que el receptor no esté confundiendo su propia credencial de API con la firma de Maildroppa. Un encabezado de autorización personalizado y X-Maildroppa-Signature tienen propósitos distintos y se pueden comprobar de forma independiente.

El receptor devuelve una redirección

Maildroppa no sigue redirecciones. Sustituye la URL del endpoint por la URL HTTPS pública final y vuelve a probar.

La firma no coincide

Confirma que el receptor:

• Utiliza el Signing secret actual.
• Utiliza el valor exacto de X-Maildroppa-Timestamp.
• Firma <timestamp>.<raw request body>.
• Utiliza HMAC-SHA256 y salida hexadecimal en minúsculas.
• Compara el valor completo, incluido v1=.
• Realiza la comparación antes de que el análisis de JSON cambie el cuerpo.

El mismo evento llega más de una vez

Esto puede suceder después de una interrupción de red, un reintento o una repetición manual. Es normal que los sistemas de entrega de webhooks proporcionen entrega al menos una vez en lugar de entrega exactamente una vez.

Utiliza el Event ID como clave de idempotencia. Devuelve una respuesta 2xx cuando se reciba de nuevo un Event ID ya procesado y no sea necesaria ninguna acción adicional.

Una entrega está Pending

Consulta «Next retry» en la columna HTTP. Un fallo reintentable 408, 429, 5xx o de red temporal permanece Pending hasta el siguiente intento programado.

Haz clic en «Refresh» después de la hora de reintento para cargar el estado más reciente.

Una entrega está Dead

Se utilizaron todos los intentos automáticos. Primero soluciona el receptor, asegúrate de que el endpoint esté Active, envía un Test webhook y, a continuación, utiliza Replay en la entrega de producción.

Lista de comprobación recomendada para producción

Antes de depender de un endpoint en producción, confirma todo lo siguiente:

1. El receptor utiliza una URL HTTPS pública estable con un certificado válido.
2. El Signing secret se almacena fuera del código fuente.
3. La firma se comprueba con el cuerpo sin procesar y sin modificar.
4. Las marcas de tiempo antiguas se rechazan según una tolerancia documentada.
5. El receptor almacena y deduplica Event ID.
6. El receptor registra Event ID y Delivery ID para el seguimiento.
7. El procesamiento lento ocurre después de que el evento se haya aceptado de forma duradera.
8. Se devuelve una respuesta 2xx solo para eventos aceptados.
9. Las credenciales personalizadas se almacenan en encabezados en lugar de en la URL.
10. Solo se seleccionan los tipos de evento necesarios.
11. Un Test webhook tiene éxito y aparece correctamente en Delivery history.
12. La supervisión te alerta cuando las entregas de producción empiezan a devolver errores.

Con estas medidas de seguridad implementadas, la página Webhooks proporciona ambos lados de una integración fiable: entrega segura de eventos a tu aplicación y un historial operativo claro dentro de Maildroppa.