Descripción General de Webhooks

Los webhooks entregan notificaciones HTTP en tiempo real a su servidor cuando ocurren eventos de correo electrónico, entregas, rebotes, quejas y más. En lugar de consultar periódicamente los cambios de estado, MailLand envía los eventos a su endpoint en el momento en que ocurren.

Cómo Funcionan los WebhooksCopiar enlace de la sección

Crear un WebhookCopiar enlace de la sección

POST https://api.mail.land/v1/webhooks

curl -X POST https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains"
  }'

Campos de la SolicitudCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Estado: 201 Created

{
  "webhook": {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains",
    "domainIds": [],
    "isActive": true,
    "createdAt": "2026-02-17T10:00:00Z",
    "successCount": 0,
    "failureCount": 0,
    "consecutiveFailures": 0,
    "pauseThreshold": 10
  },
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
}

Listar WebhooksCopiar enlace de la sección

GET https://api.mail.land/v1/webhooks

curl -X GET https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced"],
    "isActive": true,
    "lastTriggeredAt": "2026-02-17T12:30:00Z",
    "lastSuccessAt": "2026-02-17T12:30:00Z",
    "successCount": 1542,
    "failureCount": 3,
    "consecutiveFailures": 0,
    "createdAt": "2026-02-10T08:00:00Z"
  }
]

Devuelve hasta 100 webhooks ordenados por fecha de creación (más reciente primero).

Obtener Detalle del WebhookCopiar enlace de la sección

GET https://api.mail.land/v1/webhooks/{id}

curl -X GET https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve la configuración completa del webhook más los 50 registros de entrega más recientes. Consulte Lógica de Reintentos para detalles de los registros de entrega.

Actualizar un WebhookCopiar enlace de la sección

PUT https://api.mail.land/v1/webhooks/{id}

curl -X PUT https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Events",
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "isActive": true
  }'

Todos los campos son opcionales: incluya solo los campos que desea cambiar.

Probar un WebhookCopiar enlace de la sección

Envíe un evento de prueba para verificar que su endpoint funciona:

POST https://api.mail.land/v1/webhooks/{id}/test

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "statusCode": 200,
  "statusText": "OK",
  "durationMs": 145,
  "responseBody": "{\"received\": true}",
  "headersSent": {
    "X-MLND-Signature": "t=1708171200,v1=abc123...",
    "X-MLND-Event-Id": "evt_test_abc123",
    "X-MLND-Event-Version": "1",
    "X-MLND-Event": "webhook.test",
    "X-MLND-Webhook-Id": "k3m9x2p7qw4rtz",
    "X-MLND-Attempt": "1"
  },
  "wouldReceiveRealEvents": true,
  "liveEvents": ["message.delivered", "message.bounced"],
  "dormantEvents": {},
  "subscriptionWarning": null
}

El envío de prueba usa la misma firma y el mismo transporte de entrega que un evento real, así que un éxito aquí demuestra su URL, su TLS y su verificación de firma.

No demuestra su suscripción: una prueba se envía bajo demanda y no se enruta según su selección de eventos. Los cuatro últimos campos lo responden por separado:

Un "success": true junto con "wouldReceiveRealEvents": false es el caso importante: el endpoint funciona pero no está suscrito a nada que pueda entregarse.

Si la prueba falla, el campo errorType indica el motivo: ssrf_blocked (la URL, o una redirección desde ella, apuntaba a un destino al que la plataforma se niega a enviar) o network_error (tiempo de espera, fallo de TLS, conexión rechazada; errorMessage lleva el detalle).

Regenerar el SecretCopiar enlace de la sección

Si pierde o necesita rotar el secret de su webhook:

POST https://api.mail.land/v1/webhooks/{id}/regenerate-secret

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/regenerate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secretKey": "whsec_x9y8z7w6v5u4..."
}

Alcance de DominioCopiar enlace de la sección

De manera predeterminada, los webhooks reciben eventos para todos los dominios de su espacio de trabajo. Para limitar un webhook a dominios específicos:

{
  "webhookUrl": "https://your-app.com/webhooks/mailland",
  "scope": "selected_domains",
  "domainIds": ["d4n8q1zt5wm3xc", "b7r2mv9k0jy4pw"]
}

Solo los eventos relacionados con esos dominios activarán el webhook.

Pausa Automática por FallosCopiar enlace de la sección

MailLand pausa automáticamente los webhooks después de 10 fallos de entrega consecutivos (configurable por webhook mediante pauseThreshold). Esto evita desperdiciar recursos en endpoints que están caídos.

Cuando un webhook es pausado:

• Se establece la marca de tiempo pausedAt
• pausedReason describe el motivo de la pausa
• Se envía un evento account.webhook_paused a sus otros webhooks activos
• Se crea una notificación dentro de la aplicación

Reanudar un Webhook PausadoCopiar enlace de la sección

Después de solucionar el problema, reanude la entrega:

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Esta acción borra el estado de pausa, restablece el contador de fallos consecutivos y reactiva el webhook (isActive vuelve a ser true), de modo que los eventos futuros se entregan con normalidad.

Eliminar un WebhookCopiar enlace de la sección

DELETE https://api.mail.land/v1/webhooks/{id}

curl -X DELETE https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve 204 No Content. Si el webhook es utilizado por rutas de correo entrante, esas rutas serán actualizadas o deshabilitadas automáticamente.

Respuestas de ErrorCopiar enlace de la sección

Próximos PasosCopiar enlace de la sección

• Eventos: referencia completa de todos los tipos de eventos y payloads
• Verificación de Firma: verificar la autenticidad del webhook
• Lógica de Reintentos: comprender el comportamiento de reintentos y el manejo de fallos