Configuración de Webhooks

Esta guía te mostrará cómo configurar y gestionar webhooks en tu cuenta de Docutray.

Crear un Nuevo Webhook

Paso 1: Acceder a la configuración de webhooks

1. Inicia sesión en tu cuenta de Docutray en https://app.docutray.com/login

2. Selecciona la organización con la que deseas trabajar

3. Navega a "Configuración" > "Organización" > "Webhooks" en el menú de navegación

Paso 2: Crear un nuevo webhook

1. Haz clic en el botón "Añadir Webhook"

2. Completa los campos requeridos en el formulario:

• URL del Endpoint: La URL HTTPS donde recibirás las notificaciones
• Eventos: Selecciona los tipos de eventos que deseas recibir:
  • Eventos de Conversión: CONVERSION_STARTED, CONVERSION_COMPLETED, CONVERSION_FAILED
  • Eventos de Identificación: IDENTIFICATION_STARTED, IDENTIFICATION_COMPLETED, IDENTIFICATION_FAILED
  • Eventos de Steps: STEP_STARTED, STEP_COMPLETED, STEP_FAILED
• Activado: Permite activar o desactivar el webhook

3. Haz clic en "Crear Webhook"

4. Importante: Copia y guarda el secreto que se genera automáticamente. Este secreto se usa para verificar la autenticidad de las solicitudes.

Paso 3: Configurar tu endpoint

Tu endpoint debe cumplir con los siguientes requisitos:

• Protocolo: Ser accesible públicamente vía HTTPS
• Respuesta: Responder con un código de estado 200-299 para confirmar recepción
• Formato: Procesar solicitudes POST con Content-Type application/json
• Tiempo de respuesta: Responder en menos de 30 segundos

Gestión de Webhooks

Ver webhooks configurados

En la página de webhooks puedes ver todos los webhooks configurados:

Editar un webhook

1. Haz clic en el menú de opciones (⋯) del webhook que deseas editar
2. Selecciona "Editar"
3. Modifica los campos necesarios
4. Haz clic en "Actualizar Webhook"

Activar/Desactivar un webhook

Puedes activar o desactivar un webhook usando el interruptor en la lista de webhooks, sin necesidad de eliminarlo.

Regenerar secreto

Si necesitas cambiar el secreto:

1. Haz clic en el menú de opciones (⋯) del webhook
2. Selecciona "Regenerar secreto"
3. Copia y guarda el nuevo secreto

Nota: El secreto anterior dejará de funcionar inmediatamente.

Eliminar un webhook

1. Haz clic en el menú de opciones (⋯) del webhook
2. Selecciona "Eliminar"
3. Confirma la eliminación

Nota: Esta acción no se puede deshacer.

Estructura de Datos

Headers HTTP

Cada solicitud webhook incluye los siguientes headers:

Content-Type: application/json
User-Agent: Docutray-Webhook/1.0
X-Docutray-Signature: sha256=<hmac_signature_body>
X-Docutray-Auth-Signature: sha256=<hmac_signature_auth>
X-Docutray-Timestamp: <unix_timestamp>
X-Docutray-Request-Id: <uuid>
X-Docutray-Event: <event_type>

Descripción de Headers

• X-Docutray-Signature: Firma HMAC basada en el cuerpo del mensaje
• X-Docutray-Auth-Signature: Firma HMAC basada en metadatos (para Lambda Authorizers)
• X-Docutray-Timestamp: Timestamp Unix en segundos
• X-Docutray-Request-Id: UUID único para cada envío
• X-Docutray-Event: Tipo de evento (ej: CONVERSION_COMPLETED)

Recomendaciones

Confiabilidad

• Responde rápidamente (dentro de 30 segundos)
• Implementa procesamiento idempotente
• Registra los eventos recibidos para debugging
• Usa una cola de mensajes para procesamiento asíncrono si es necesario

Manejo de errores

• Docutray reintentará hasta 5 veces con backoff exponencial
• Si tu endpoint no responde consistentemente, el webhook puede ser desactivado automáticamente
• Los reintentos siguen esta secuencia: 30s, 1min, 5min, 15min, 1hora

Testing

• Usa herramientas como webhook.site para probar la recepción de webhooks
• Implementa un endpoint de prueba antes de producción
• Verifica que tu firewall permite conexiones desde los servidores de Docutray

Próximos Pasos

• Seguridad: Implementa verificación de firmas para proteger tu endpoint
• Eventos de Conversión: Aprende sobre webhooks de conversión de documentos
• Eventos de Identificación: Aprende sobre webhooks de identificación
• Eventos de Steps: Aprende sobre webhooks de steps
• Ejemplos: Revisa código de ejemplo para implementar webhooks