PiiBlur

'Comment créer un pipeline de rédaction basé sur un webhook'

'PiiBlur Team'7 lecture min.

Le sondage est très bien pour un prototype. Un workflow de rédaction de production nécessite généralement des webhooks.

La raison est simple : la rédaction d’images et de vidéos est asynchrone. Votre application télécharge un fichier, PiiBlur met la tâche en file d'attente et le résultat devient disponible plus tard. Si les travailleurs restent assis à interroger chaque tâche, ils gaspillent de la capacité et rendent la gestion des échecs plus difficile. Un pipeline de webhook permet aux travailleurs de téléchargement de soumettre des tâches rapidement, puis à un gestionnaire distinct de gérer les fichiers terminés.

Cet article décrit la forme de ce pipeline. Il n'est pas lié à un fournisseur de file d'attente spécifique ; le même modèle fonctionne avec les files d'attente SQS, Redis, RabbitMQ, Sidekiq, Laravel ou une table de tâches basée sur une base de données.

La forme du pipeline

Un pipeline de rédaction fiable comporte cinq éléments :

  1. Stockage source - où se trouve actuellement l'image ou la vidéo d'origine.
  2. Travailleur de soumission - envoie le fichier à /api/v1/media/redact.
  3. Tableau des tâches - enregistre votre ID d'objet interne, l'ID de média PiiBlur, l'état, les catégories sélectionnées et le nombre de tentatives.
  4. Point de terminaison Webhook : reçoit les événements media.processed et media.failed.
  5. Télécharger le travailleur : récupère la sortie rédigée et la stocke dans votre compartiment final.

Gardez la soumission et le téléchargement séparés. Le téléchargement de 10 000 images ne doit pas attendre la fin des 10 premières.

Soumettre des tâches avec des clés d'idempotence

Utilisez une clé d'idempotence pour chaque actif source. Si un délai d'attente réseau se produit après que PiiBlur ait reçu le téléchargement, votre nouvelle tentative peut répéter la demande en toute sécurité.

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"

Conservez la clé d'idempotence à côté de votre dossier d'actif interne. Ne générez pas de clé aléatoire à chaque nouvelle tentative ; cela va à l’encontre du but.

Un format de clé utile inclut l'ID de l'actif source et un numéro de version :

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

Incrémentez la version uniquement lorsque la sélection de fichier ou de catégorie change.

Enregistrez suffisamment d'état pour déboguer les échecs

Votre table de travail ne devrait pas être une réflexion après coup. Au minimum, stockez :

  • ID d'actif interne
  • ID média PiiBlur
  • Nom du fichier d'origine
  • Type de média
  • Catégories PII sélectionnées
  • Méthode de rédaction
  • Statut de soumission
  • Statut de traitement
  • Nombre de nouvelles tentatives
  • Dernier code d'erreur et ID de demande
  • Horodatages pour les soumissions, les traitements, les échecs et les téléchargements

Le request_id des erreurs API est particulièrement utile. Enregistrez-le avec votre propre ID de travail afin que l'assistance puisse retracer la demande en cas d'échec.

Vérifier les signatures des webhooks

Traitez les demandes de webhook comme non fiables jusqu'à ce que la signature soit vérifiée. PiiBlur envoie un en-tête X-PiiBlur-Signature. Votre gestionnaire doit calculer le HMAC attendu sur le corps brut de la requête et le comparer avec une fonction de comparaison à temps constant.

Rejetez les demandes qui échouent à la vérification de la signature. Ne mettez pas à jour l’état du travail à partir d’une charge utile non signée.

Rendre les gestionnaires de webhooks ennuyeux

Une erreur courante consiste à en faire trop dans la requête HTTP webhook. Gardez le gestionnaire court :

  1. Vérifiez la signature.
  2. Analysez l'événement.
  3. Insérez l'ID d'événement dans une table de déduplication.
  4. Mettez à jour le statut du travail.
  5. Mettez en file d'attente une tâche de téléchargement ou de révision.
  6. Renvoyez 200 OK.

Le téléchargement réel peut s'exécuter dans un gestionnaire de file d'attente. Cela vous donne des tentatives, des délais d'attente et une observabilité sans que PiiBlur attende votre fournisseur de stockage.

Événements de déduplication

Les systèmes de diffusion de webhooks peuvent réessayer. Votre point de terminaison doit être idempotent.

Utilisez l'ID d'événement comme clé de déduplication. Si votre base de données possède déjà cet ID d'événement, renvoyez 200 OK et ne faites rien. Cela évite les doubles téléchargements et les transitions de statut en double.

Rendre également les mises à jour de statut monotones. Une tâche terminée ne doit pas être remise en file d'attente car un ancien événement est arrivé en retard.

Télécharger seulement une fois terminé

La réponse d'état du support inclut un download_url uniquement lorsque le traitement est terminé. Votre agent de téléchargement doit :

  1. Lisez l'ID du média dans votre table de tâches.
  2. Récupérez l'URL de téléchargement ou utilisez l'URL de la charge utile du webhook traité.
  3. Téléchargez avec la même clé API Bearer.
  4. Stockez le fichier rédigé dans votre propre compartiment.
  5. Marquez le travail comme téléchargé.

Conservez les originaux et les sorties rédigées dans des chemins séparés. Par exemple:

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

Cette séparation rend moins probable la publication accidentelle des originaux.

Politique de nouvelle tentative

Tous les échecs ne devraient pas réessayer de la même manière.

  • Délai d'expiration du réseau - réessayez avec une interruption exponentielle.
  • HTTP 429 - respectez Retry-After, puis réessayez.
  • HTTP 500 - réessayez un petit nombre de fois.
  • HTTP 409 - vérifiez si la clé d'idempotence est toujours en cours de traitement ou a été réutilisée avec une charge utile différente.
  • HTTP 422 - ne réessayez pas tant que le fichier ou la demande n'est pas corrigé.

Après la dernière tentative, déplacez le travail vers une file d'attente de lettres mortes. Un humain devrait être capable de voir le fichier, le code d’erreur, les catégories sélectionnées et l’ID de la demande sans fouiller dans les journaux.

Vérifier les règles

La rédaction automatisée n’est pas une raison pour ignorer l’examen des médias à haut risque. Ajoutez des portes de révision pour :

  • Images de diffusion publique
  • Preuve juridique
  • Dossiers de santé ou d'éducation
  • Médias impliquant des enfants
  • Toute sortie dont le fichier source était en basse résolution, flou, sombre ou fortement compressé

Les flux de travail internes à faible risque peuvent souvent utiliser l'échantillonnage à la place. Examinez 1 à 5 % des résultats terminés, suivez les échecs et ajustez la sélection des catégories si l'échantillon révèle une tendance.

Pages API associées

Pour connaître les paramètres de requête exacts, consultez le fichier Documentation API. Pour des exemples ciblés, consultez les pages API de flou de visage, API de flou de plaque d'immatriculation, API de rédaction d'images et API de rédaction vidéo.