Workflow AI asincron cu webhooks, cozi de mesaje și Dead Letter Queue pentru sarcinile eșuate

Un workflow AI nu ar trebui să țină o conexiune HTTP deschisă câteva minute cât timp analizează un PDF, generează un raport sau așteaptă răspunsul unui model extern. Dacă operația durează prea mult, furnizorul webhookului poate considera cererea eșuată și o poate retrimite. Rezultatul poate fi procesarea aceleiași sarcini de două sau trei ori.

Arhitectura sigură separă primirea evenimentului de execuția propriu-zisă:

Webhook
→ validare și salvare
→ mesaj în coadă
→ worker AI
→ rezultat
→ notificare sau callback

Webhookul trebuie să răspundă rapid, iar operația costisitoare rulează ulterior. Stripe recomandă trimiterea rapidă a răspunsului 2xx și mutarea proceselor lungi în afara endpointului webhook, tocmai pentru a evita timeouturile și livrările repetate.

Primește webhookul fără să rulezi AI-ul direct

Endpointul trebuie să facă doar câteva operații:

verifică semnătura;
validează tipul evenimentului;
verifică dacă evenimentul a mai fost primit;
salvează datele minime;
publică un mesaj în coadă;
răspunde cu 202 Accepted.

GitHub recomandă verificarea semnăturii înainte de orice procesare, folosind secretul webhookului și antetul X-Hub-Signature-256. Aceeași idee se aplică oricărui furnizor: nu te baza doar pe adresa IP sau pe un câmp din payload.

Un mesaj pentru coadă poate arăta astfel:

{
  "job_id": "job_91c740",
  "event_id": "evt_48320",
  "task_type": "summarize_document",
  "input_ref": "documents/doc_781",
  "user_id": "user_204",
  "attempt": 0,
  "created_at": "2026-07-27T10:15:00Z"
}

Nu introduce în mesaj întregul document, parole, tokenuri sau date personale inutile. Păstrează fișierul într-un storage controlat și trimite în coadă doar un identificator.

Workerul preia și procesează sarcina

Workerul citește mesajul, încarcă documentul, apelează modelul AI și salvează rezultatul. Mesajul este confirmat și eliminat numai după finalizarea cu succes.

În Amazon SQS, mesajul devine temporar invizibil după preluare. Dacă workerul nu îl șterge înainte de expirarea visibility timeout, mesajul reapare și poate fi procesat din nou. Timeoutul trebuie să fie mai mare decât durata obișnuită a operației sau prelungit periodic pentru sarcinile lungi.

Coada poate livra același mesaj de mai multe ori. Amazon SQS Standard folosește modelul at-least-once, iar documentația recomandă proiectarea operațiilor idempotente.

Înainte de procesare, workerul verifică:

if job_already_completed(job_id):
    acknowledge_message()
    return

Pentru emailuri, plăți sau publicări, folosește o cheie unică:

idempotency_key = job_id + ":" + action_name

Astfel, relivrarea mesajului nu trimite același email de două ori.

Aplică retry numai pentru erori temporare

Nu orice eroare merită reîncercată.

Erori temporare:

timeout către modelul AI;
răspuns HTTP 429;
indisponibilitate 502 sau 503;
conexiune întreruptă;
limită temporară de resurse.

Erori permanente:

fișier inexistent;
format neacceptat;
utilizator fără permisiune;
payload invalid;
document prea mare pentru politica aplicației.

Pentru erorile temporare folosește exponential backoff cu jitter:

30 secunde
→ 2 minute
→ 10 minute
→ 30 minute

Celery permite reexecutarea taskului cu același task ID și înregistrarea retry-ului în starea sarcinii. Numărul încercărilor trebuie să fie limitat; retry infinit poate bloca workerii și crește costurile.

Mută sarcinile nerecuperabile în Dead Letter Queue

După un număr stabilit de încercări, mesajul nu trebuie reintrodus la nesfârșit în coada principală. Este mutat într-o Dead Letter Queue, prescurtat DLQ.

Mesajul din DLQ trebuie să păstreze:

job_id
tipul erorii
numărul încercărilor
ultima excepție
momentul eșecului
workerul și versiunea aplicației
referința către input

AWS configurează mutarea printr-o redrive policy și maxReceiveCount. Microsoft Azure Service Bus folosește o subcoadă DLQ pentru mesajele care nu au putut fi procesate, iar RabbitMQ poate retransmite mesajele către un Dead Letter Exchange.

DLQ nu este coș de gunoi. Configurează alerte pentru:

numărul mesajelor;
vârsta celui mai vechi mesaj;
tipurile frecvente de eroare;
creșteri bruște ale ratei de eșec.

După remedierea cauzei, un operator verifică mesajul și îl retrimite controlat în coada principală. Nu face redrive automat fără să corectezi problema, altfel creezi o buclă între coadă și DLQ.

Un workflow AI robust nu promite că toate sarcinile reușesc din prima. El garantează că evenimentele sunt validate, taskurile nu se dublează, erorile temporare sunt reîncercate controlat, iar cazurile nerecuperabile rămân vizibile și pot fi investigate.

Surse folosite

Stripe Docs – Webhooks și procesarea asincronă
GitHub Docs – Validating Webhook Deliveries și Webhook Best Practices
Amazon Web Services – SQS Visibility Timeout, At-Least-Once Delivery și Dead-Letter Queues
Microsoft Learn – Azure Service Bus Dead-Letter Queues
RabbitMQ – Dead Letter Exchanges
Celery Documentation – Task Retry și Retry Policies