Saltar al contenido

Webhooks

Endpoints que reciben los eventos de tus emails.

Listar endpoints de webhook

GET/v1/webhooks

Scope necesario: read o full. Una clave full incluye send y read.

Solo los del entorno de la clave. El secreto nunca sale aquí (secretMasked).

Cada petición lleva Vemudo-Signature: t=<unix s>,v1=<hex>. Durante las 24 h siguientes a rotar el secreto lleva dos v1= (el nuevo primero). La firma es HMAC-SHA256(secret, t + "." + rawBody) en hex sobre el cuerpo crudo. Rechaza las peticiones con t de hace más de 5 min y deduplica por Vemudo-Event-Id: una entrega puede repetirse (al menos una vez) y no hay garantía de orden entre eventos. Cabeceras: Content-Type, User-Agent: Vemudo-Webhooks/1.0, Vemudo-Event-Id, Vemudo-Delivery-Attempt y Vemudo-Signature. Responde 2xx en menos de 10 s; no se siguen redirecciones; si falla se reintenta durante 72 h (1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 12 h...).

Verificación en Node:

js
const crypto = require('node:crypto');
function verify(rawBody, header, secret) {
  const parts = header.split(',');
  const t = Number(parts.find((p) => p.startsWith('t=')).slice(2));
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const got = p.slice(3);
      return (
        got.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
      );
    });
}

Respuestas

  • 200
    { data: [WebhookEndpoint] }.
    CampoDescripción
    data[]object[] · obligatorio
    data[].idstring · obligatorio
    data[].urlstring · obligatorio
    data[].descriptionstring | null · obligatorio
    data[].environmentstring · obligatoriovalores: test | live
    data[].eventTypesstring[] · obligatoriovalores: email.sent | email.delivered | email.deferred | email.bounced | email.complained | email.suppressed | email.rejected | email.failed | email.cancelled
    data[].statusstring · obligatoriovalores: active | disabled
    data[].disabledReasonstring | null · obligatorio
    data[].disabledAtstring | null · obligatorio
    data[].failingSincestring | null · obligatorio
    data[].failureCountnumber · obligatorio
    data[].lastSuccessAtstring | null · obligatorio
    data[].lastFailureAtstring | null · obligatorio
    data[].lastStatusCodenumber | null · obligatorio
    data[].secretMaskedstring | null · obligatorionull para el rol viewer.ej.: whsec_••••hJ0f
    data[].secretPreviousExpiresAtstring | null · obligatorio
    data[].createdAtstring · obligatorio

Ejemplo

bash
curl https://api.vemudo.com/v1/webhooks \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

Crear un endpoint de webhook

POST/v1/webhooks

Scope necesario: full. Una clave full incluye send y read.

Devuelve el secreto de firma (whsec_...) una sola vez. Máximo 10 endpoints por organización y 20 altas por hora (429 rate_limited). La URL debe ser HTTPS pública (422 webhook_url_not_allowed si apunta a una red privada). Eventos disponibles: email.sent, email.delivered, email.deferred, email.bounced, email.complained, email.suppressed, email.rejected, email.failed, email.cancelled; el cuerpo de cada uno es WebhookEvent.

Cuerpo application/json

CampoDescripción
urlstring · obligatorioURL HTTPS (puerto 443 o 1024-65535, sin credenciales ni fragmento, hasta 2048 caracteres). Debe resolver a una IP pública y responder 2xx en menos de 10 s.ej.: https://api.tiendaalbar.es/webhooks/vemudo
eventTypesstring[] · obligatorioEventos a recibir (al menos uno, sin repetir).valores: email.sent | email.delivered | email.deferred | email.bounced | email.complained | email.suppressed | email.rejected | email.failed | email.cancelled · ej.: ["email.delivered","email.bounced"]
descriptionobject Texto libre de hasta 100 caracteres.

Respuestas

  • 201
    Endpoint creado: { ...WebhookEndpoint, secret }.
    CampoDescripción
    idstring · obligatorio
    urlstring · obligatorio
    descriptionstring | null · obligatorio
    environmentstring · obligatoriovalores: test | live
    eventTypesstring[] · obligatoriovalores: email.sent | email.delivered | email.deferred | email.bounced | email.complained | email.suppressed | email.rejected | email.failed | email.cancelled
    statusstring · obligatoriovalores: active | disabled
    disabledReasonstring | null · obligatorio
    disabledAtstring | null · obligatorio
    failingSincestring | null · obligatorio
    failureCountnumber · obligatorio
    lastSuccessAtstring | null · obligatorio
    lastFailureAtstring | null · obligatorio
    lastStatusCodenumber | null · obligatorio
    secretMaskedstring | null · obligatorionull para el rol viewer.ej.: whsec_••••hJ0f
    secretPreviousExpiresAtstring | null · obligatorio
    createdAtstring · obligatorio
    secretstring · obligatorioSecreto de firma. Solo se muestra en esta respuesta.ej.: whsec_0123456789abcdefghijklmnopqrstuv

Ejemplo

bash
curl -X POST https://api.vemudo.com/v1/webhooks -H "Authorization: Bearer $VEMUDO_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/hooks/vemudo","eventTypes":["email.delivered","email.bounced"]}'

Borrar un endpoint de webhook

DELETE/v1/webhooks/{id}

Scope necesario: full. Una clave full incluye send y read.

Borra también sus entregas. 404 si no existe o es del otro entorno. Responde 204.

Parámetros

CampoDescripción
idstring · ruta · obligatorio

Respuestas

  • 200
    Sin contenido.

Ejemplo

bash
curl -X DELETE https://api.vemudo.com/v1/webhooks/$ID \
  -H "Authorization: Bearer $VEMUDO_API_KEY"