'Cómo crear un canal de redacción basado en webhooks'

El sondeo está bien para un prototipo. Un flujo de trabajo de redacción de producción normalmente necesita webhooks.

La razón es simple: la redacción de imágenes y videos es asincrónica. Su aplicación carga un archivo, PiiBlur pone en cola el trabajo y el resultado estará disponible más tarde. Si los trabajadores se sientan a sondear cada trabajo, desperdician capacidad y dificultan el manejo de fallas. Una canalización de webhook permite que los trabajadores de carga envíen trabajos rápidamente y luego permite que un controlador independiente se ocupe de los archivos completados.

Este artículo describe la forma de esa tubería. No está vinculado a un proveedor de cola específico; El mismo patrón funciona con colas SQS, Redis, RabbitMQ, Sidekiq, Laravel o una tabla de trabajos respaldada por una base de datos.

La forma de la tubería

Un proceso de redacción confiable consta de cinco partes:

1. Almacenamiento de origen: lugar donde se encuentra actualmente la imagen o el video original.
2. Trabajador de envío: envía el archivo a /api/v1/media/redact.
3. Tabla de trabajos: registra su ID de objeto interno, el ID de medio PiiBlur, el estado, las categorías seleccionadas y el recuento de reintentos.
4. Punto final de webhook: recibe eventos media.processed y media.failed.
5. Trabajador de descarga: recupera el resultado redactado y lo almacena en el depósito final.

Mantenga el envío y la descarga por separado. La carga de 10.000 imágenes no debe esperar a que finalicen las 10 primeras.

Enviar trabajos con claves de idempotencia

Utilice una clave de idempotencia para cada activo de origen. Si se agota el tiempo de espera de la red después de que PiiBlur reciba la carga, su reintento puede repetir la solicitud de manera segura.

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: claim-photo-78391-v1" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=license_plates" \
  -F "redaction_method=blur"

Guarde la clave de idempotencia junto a su registro de activos interno. No genere una clave aleatoria en cada reintento; eso derrota el punto.

Un formato de clave útil incluye el ID del activo de origen y un número de versión:

• listing-photo-44822-v1
• dashcam-segment-20260608-0915-v2
• claim-photo-78391-v1

Incremente la versión solo cuando cambie la selección de archivo o categoría.

Registre suficiente estado para depurar fallas

Tu mesa de trabajo no debería ser una ocurrencia tardía. Como mínimo, almacene:

• ID de activo interno
• ID de medio PiiBlur
• Nombre de archivo original
• Tipo de medio
• Categorías de PII seleccionadas
• Método de redacción
• Estado de envío
• Estado de procesamiento
• Recuento de reintentos
• Último código de error e ID de solicitud
• Marcas de tiempo enviadas, procesadas, fallidas y descargadas

El request_id de errores de API es especialmente útil. Regístrelo con su propio ID de trabajo para que el soporte pueda rastrear la solicitud si algo falla.

Verificar firmas de webhooks

Trate las solicitudes de webhook como no confiables hasta que se verifique la firma. PiiBlur envía un encabezado X-PiiBlur-Signature. Su controlador debe calcular el HMAC esperado sobre el cuerpo de la solicitud sin formato y compararlo con una función de comparación de tiempo constante.

Rechace solicitudes que no superen la verificación de firma. No actualice el estado del trabajo desde una carga útil sin firmar.

Hacer que los controladores de webhooks sean aburridos

Un error común es hacer demasiado dentro de la solicitud de webhook HTTP. Mantenga el controlador breve:

1. Verificar la firma.
2. Analice el evento.
3. Inserte el ID del evento en una tabla de deduplicación.
4. Actualice el estado del trabajo.
5. Ponga en cola una tarea de descarga o revisión.
6. Devuelve 200 OK.

La descarga real puede ejecutarse en un trabajador de cola. Eso le brinda reintentos, tiempos de espera y observabilidad sin hacer que PiiBlur espere a su proveedor de almacenamiento.

Deduplicar eventos

Los sistemas de entrega de webhooks pueden volver a intentarlo. Su punto final debe ser idempotente.

Utilice el ID del evento como clave de deduplicación. Si su base de datos ya tiene ese ID de evento, devuelva 200 OK y no haga nada. Esto evita descargas dobles y transiciones de estado duplicadas.

También haga que las actualizaciones de estado sean monótonas. Un trabajo completado no debe volver a ponerse en cola porque un evento anterior llegó tarde.

Descargar solo después de completar

La respuesta del estado de los medios incluye un download_url solo cuando se completa el procesamiento. Su trabajador de descarga debería:

1. Lea la identificación del medio en su tabla de trabajos.
2. Obtenga la URL de descarga o utilice la URL de la carga útil del webhook procesado.
3. Descargue con la misma clave Bearer API.
4. Guarde el archivo redactado en su propio depósito.
5. Marque el trabajo como descargado.

Mantenga los originales y los resultados redactados en rutas separadas. Por ejemplo:

s3://media-originals/claims/78391/photo.jpg
s3://media-redacted/claims/78391/photo.jpg

Esa separación hace que sea menos probable la publicación accidental de originales.

Política de reintento

No todos los fracasos deberían volver a intentarlo de la misma manera.

• Tiempo de espera de la red: reintento con retroceso exponencial.
• HTTP 429 - respeta Retry-After, luego vuelve a intentarlo.
• HTTP 500: reinténtalo un pequeño número de veces.
• HTTP 409: compruebe si la clave de idempotencia todavía se está procesando o se reutilizó con una carga útil diferente.
• HTTP 422: no vuelva a intentarlo hasta que se solucione el archivo o la solicitud.

Después del último reintento, mueva el trabajo a una cola de mensajes fallidos. Un humano debería poder ver el archivo, el código de error, las categorías seleccionadas y solicitar ID sin tener que buscar en los registros.

Revisar reglas

La redacción automatizada no es motivo para omitir la revisión de medios de alto riesgo. Agregue puertas de revisión para:

• Imágenes de lanzamiento público
• Pruebas legales
• Registros de salud o educación.
• Medios de comunicación que involucran a niños.
• Cualquier salida en la que el archivo fuente fuera de baja resolución, borroso, oscuro o muy comprimido.

Los flujos de trabajo internos de bajo riesgo a menudo pueden utilizar el muestreo. Revise entre el 1% y el 5% de los resultados completados, realice un seguimiento de los errores y ajuste la selección de categorías si la muestra revela un patrón.

Páginas API relacionadas

Para conocer los parámetros de solicitud exactos, consulte Documentación API. Para ver ejemplos específicos, consulte las páginas API de desenfoque facial, API de desenfoque de matrícula, API de redacción de imágenes y API de redacción de vídeos.