Digito

Autenticación del receptor

Comprueba el secreto de cada entrega, valida el JSON y evita procesar avisos duplicados.

Configura un secreto en la suscripción del equipo. Digito lo incluye como valor de una cabecera de la solicitud; tu receptor debe compararlo con el secreto que guarda en su servidor.

Se trata de un secreto compartido, no de una firma HMAC del cuerpo. Utiliza HTTPS para protegerlo en tránsito, rechaza los valores ausentes o incorrectos y no registres las cabeceras completas.

Configura el receptor

Estas variables pertenecen a tu aplicación receptora:

Variable de ejemploQué configurar
DIGITO_WEBHOOK_SECRETEl mismo secreto que guardaste en el webhook del equipo. Es distinto de la clave de API.
DIGITO_WEBHOOK_SECRET_HEADEREl nombre exacto de la cabecera que lleva ese secreto en la solicitud recibida.

Confirma el nombre de la cabecera con Digito o inspecciona los encabezados de solicitud en tu propio receptor durante una prueba controlada. No lo confundas con los encabezados de respuesta que muestra el registro de entregas del portal. El nombre de la variable es una opción de este ejemplo: no crea ni cambia una cabecera del servicio.

Mantén ambas variables en el servidor o en su gestor de secretos. Nunca las expongas en el frontend. Si falta alguna, el receptor debe rechazar el procesamiento, no omitir la verificación.

Ejemplo TypeScript para Node.js

El siguiente manejador utiliza Request y Response. Separa la recepción del procesamiento: debes proporcionarle una función storeEvent que guarde el trabajo en una base de datos o cola duradera. Devuelve 2xx solo después de esa escritura.

import { createHash, timingSafeEqual } from 'node:crypto';

type WebhookJob = {
  deliveryKey: string;
  event: string;
  envelopeId: string;
  createdAt: string;
};

const supportedEvents = new Set([
  'DOCUMENT_CREATED', 'DOCUMENT_SENT', 'DOCUMENT_OPENED',
  'DOCUMENT_SIGNED', 'DOCUMENT_RECIPIENT_COMPLETED',
  'DOCUMENT_COMPLETED', 'DOCUMENT_REJECTED', 'DOCUMENT_CANCELLED',
  'DOCUMENT_REMINDER_SENT', 'RECIPIENT_EXPIRED',
  'TEMPLATE_CREATED', 'TEMPLATE_UPDATED', 'TEMPLATE_DELETED', 'TEMPLATE_USED',
]);

function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

export function createWebhookHandler(
  storeEvent: (job: WebhookJob) => Promise<void>,
) {
  const secret = process.env.DIGITO_WEBHOOK_SECRET;
  const headerName = process.env.DIGITO_WEBHOOK_SECRET_HEADER;
  if (!secret || !headerName) throw new Error('Falta la configuración del webhook');
  // Valida también el nombre de cabecera antes de aceptar tráfico.
  new Headers([[headerName, 'validation']]);
  const expected = Buffer.from(secret, 'utf8');

  return async function POST(request: Request): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response(null, { status: 405, headers: { Allow: 'POST' } });
    }

    const received = Buffer.from(request.headers.get(headerName) ?? '', 'utf8');
    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
      return new Response('No autorizado', { status: 401 });
    }

    const mediaType = request.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
    if (mediaType !== 'application/json') return new Response(null, { status: 415 });

    let raw: string;
    let body: unknown;
    try {
      raw = await request.text();
      body = JSON.parse(raw);
    } catch {
      return new Response('JSON no válido', { status: 400 });
    }

    if (!isObject(body) || typeof body.event !== 'string' ||
        !isObject(body.payload) || typeof body.payload.envelopeId !== 'string' ||
        !body.payload.envelopeId || typeof body.createdAt !== 'string' ||
        !Number.isFinite(Date.parse(body.createdAt)) ||
        typeof body.webhookEndpoint !== 'string') {
      return new Response('Estructura no válida', { status: 400 });
    }

    // Una ampliación del catálogo no debe activar acciones desconocidas.
    if (!supportedEvents.has(body.event)) return new Response(null, { status: 204 });

    const job: WebhookJob = {
      deliveryKey: createHash('sha256').update(raw).digest('hex'),
      event: body.event,
      envelopeId: body.payload.envelopeId,
      createdAt: body.createdAt,
    };

    try {
      // Guardado atómico con clave única; un duplicado ya guardado es éxito.
      await storeEvent(job);
    } catch {
      return new Response('No se pudo guardar la entrega', { status: 503 });
    }
    return Response.json({ received: true });
  };
}

Aplica un límite de tamaño de cuerpo y de solicitudes en el servidor o proxy receptor, según las necesidades de tu aplicación.

Conecta el manejador con la ruta POST de tu servidor. Implementa storeEvent con una restricción única sobre deliveryKey y guarda el trabajo pendiente en la misma operación: si la entrega ya existe, termina sin crear otra tarea. No uses una lista en memoria como sustituto del almacenamiento duradero.

La huella SHA-256 identifica cuerpos idénticos en tu receptor; no autentica la entrega ni representa un ID emitido por Digito. Dos avisos distintos pueden describir el mismo cambio: el trabajo posterior también debe ser idempotente. El ejemplo guarda solo los campos necesarios para consultar el sobre. Si necesitas otros datos, valida y protege esos campos antes de persistirlos.

Procesa el trabajo pendiente

Un proceso separado lee los trabajos guardados, recupera el sobre con la clave de API del equipo y comprueba su estado actual. Registra cuándo termina el trabajo y reintenta sus propios fallos sin repetir efectos ya realizados.

Para archivar un documento, confirma COMPLETED por API y descarga cada PDF final una sola vez. Para eventos de eliminación, contempla que el recurso ya no pueda recuperarse. Para plantillas, distingue su ID del ID del documento generado en TEMPLATE_USED.

No uses webhookEndpoint como destino de una solicitud saliente: es un dato del aviso, no una instrucción para tu servidor. Define tú mismo la base de la API y comprueba la relación del sobre con el equipo autorizado.

Comprueba la integración

  • Una solicitud sin secreto o con uno distinto recibe 401 y no guarda trabajo.
  • Un JSON mal formado recibe 400 y no guarda trabajo.
  • Si el almacenamiento falla, el receptor devuelve 503; no confirma un aviso perdido.
  • Reenviar la misma entrega no crea una segunda tarea.
  • El código 2xx confirma la recepción; supervisa también los errores del proceso posterior.

Si cambias el secreto, coordina el valor de la suscripción con el de tu servidor y comprueba una entrega de prueba. Oculta los secretos tanto en registros como en herramientas de errores y analítica.

Configurar y probar · Eventos y payloads.