Webhooks — reciba eventos de firma en tiempo real

Formato del payload

Todos los envíos comparten el mismo esquema JSON de nivel superior: `event`, `data` e `timestamp`. El nombre del evento también se repite en el encabezado `X-Certyneo-Event`, lo que permite enrutar incluso antes de analizar el cuerpo. El contenido de `data` varía según el evento, pero siempre permanece como un objeto plano de valores simples — nunca un arreglo ni un objeto anidado. Aquí hay un envío `envelope.completed` completo.

POST /webhooks/certyneo HTTP/1.1
Host: your.app
Content-Type: application/json
X-Certyneo-Event: envelope.completed
X-Certyneo-Delivery-Id: cm8f2h6a10004qr9k5p2wm3xt
X-Certyneo-Signature: 4f3d1c8b2a9e7f60d5c4b3a2918e7f6d5c4b3a2918e7f6d5c4b3a2918e7f6d5c

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "sandbox": false,
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "signatureLevel": "ADVANCED",
    "aesSignerCount": 2,
    "completedAt": "2026-05-27T08:42:13.000Z",
    "recipientCount": 2,
    "recipients": [
      { "email": "alice@acme.com", "name": "Alice Martin", "role": "SIGNER", "status": "SIGNED" },
      { "email": "bob@acme.com", "name": "Bob Durand", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

signedDocumentUrl es un enlace prefirmado válido durante 7 días a partir del evento: evita una segunda llamada autenticada para recuperar el PDF. Está ausente — y no nulo — si la prefirma falló, o en una envoltura QES completada sin documento almacenado; vuelva a pasar por GET /v1/envelopes/id/signed-document, que sigue siendo la fuente de verdad. Tenga cuidado también con la reproducción manual desde la cola de letras muertas más de 7 días después del evento: el enlace en el payload ha expirado, el endpoint de API no.

El payload está codificado en UTF-8, sin BOM. La firma HMAC se calcula sobre el body bruto tal como se envió — no altere espacios, el re-parsing JSON a menudo modifica el orden de las claves y rompe la verificación.

Verificar la firma HMAC

Cada solicitud se firma con su secreto de webhook (mostrado una sola vez al crear la suscripción). La firma se transmite en el encabezado `X-Certyneo-Signature`: es el HMAC-SHA256 del cuerpo bruto de la solicitud, codificado en hexadecimal, sin prefijo ni marca de tiempo. SIEMPRE verifique la firma antes de procesar el payload — sin este paso, cualquiera puede falsificar un evento y llamar a su endpoint.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // X-Certyneo-Signature = HMAC-SHA256(secret, rawBody), hex-encoded.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signatureHeader, "hex");
  const computed = Buffer.from(expected, "hex");

  // timingSafeEqual throws when the two buffers differ in length —
  // a malformed header must return false, not crash the handler.
  if (received.length !== computed.length) return false;

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(computed, received);
}

import hashlib
import hmac


def verify_certyneo_signature(
    raw_body: bytes, signature_header: str, secret: str
) -> bool:
    """Verify a Certyneo webhook signature.

    `X-Certyneo-Signature` holds the hex-encoded HMAC-SHA256 of the
    raw request body, computed with your webhook secret.
    """
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

Política de reintentos

Si tu endpoint tarda demasiado en responder, rechaza la conexión o devuelve un 5xx (o un 429), reintentamos según un backoff exponencial: 5 intentos en total, durante aproximadamente 1 h 20. Después del quinto, el evento va a la dead-letter queue — consultable y reproducible desde tu panel, pero sin reintentos automáticos. Un rechazo explícito (401, 403, 404, 410, 422…) nunca se reintenta: la respuesta no cambiaría, el evento va directamente a la dead-letter queue.

Los plazos indicados son mínimos: el barrido de reintentos está cadenciado por un cron, por lo que un intento puede salir ligeramente después de la hora teórica. Los eventos abandonados se enumeran en Webhooks → Fallos, con un botón de reproducción manual y sin límite de duración de conservación. Un endpoint que encadena cinco fallos definitivos — o que responde 404 / 410 — se desactiva automáticamente, y se te notifica por correo electrónico: reactívalo una vez corregido, el contador vuelve a cero (cualquier entrega exitosa también lo reinicia a cero).

Probar sin enviar un sobre real

Primero cree una suscripción — la respuesta contiene el `secret` necesario para la verificación HMAC, mostrado una sola vez. Desde Configuración → Webhooks, el botón « Probar » luego envía un POST firmado exactamente como una entrega real y le muestra la respuesta bruta de su servidor: es la forma más rápida de validar su controlador, localmente a través de ngrok o en integración continua.

# Create a subscription — "secret" is returned once, store it now.
curl -X POST https://api.certyneo.com/v1/webhooks \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/certyneo",
    "events": ["envelope.completed", "recipient.signed"]
  }'

La URL debe ser públicamente accesible en HTTPS: una dirección privada o localhost es rechazada por la protección SSRF al momento de crear la suscripción.

Las suscripciones están separadas por entorno, como las claves: un webhook creado con una clave sk_test_ solo recibe los eventos de los sobres de prueba, y uno creado con una clave sk_live_ solo los de los sobres reales. Un sobre de prueba nunca llega a su URL de producción, y cada carga útil indica «sandbox» (true o false).

Para ir más allá

• Hub desarrollador
• API de firma electrónica
• Integraciones nativas
• Página de seguridad
• Planes y precios