# Što ćete izgraditi#
Ovaj vodič pokazuje kako implementirati Next.js pozadinske poslove s n8n na način koji preživljava timeoute, ponovne pokušaje, duplikate i parcijalne kvarove. Cilj je jednostavan: vaša Next.js aplikacija treba brzo odgovarati, dok n8n pouzdano obrađuje dugotrajni posao.
Izgradit ćete obrazac pogodan za produkciju uz:
- Postgres tablicu reda (queue table) za perzistiranje namjere i stanja posla
- Next.js API rutu koja stavlja posao u red i okida n8n putem webhooka
- n8n workflow koji preuzima poslove, obavlja posao i koristi ključeve idempotencije kako bi postigao exactly-once učinke
- Retry politike i dead-letter tok za neuspjele poslove
- Status callback iz n8n-a prema vašoj aplikaciji kako bi se UI sigurno ažurirao
Ako ste ikad naletjeli na serverless timeout, naplatili plaćanje dvaput ili poslali duple emailove, ovo je arhitektura koja sprječava takve ishode.
Povezana detaljna objašnjenja koja bi vam mogla dobro doći uz ovaj članak:
- Obrasci Postgres queue i outbox za pouzdane integracije: n8n Postgres queue outbox pattern reliable integrations
- Kada koristiti redove, cron i job runnere u Next.js-u: Next.js background jobs queues cron Vercel
- Idempotencija, konkurentnost i race conditioni u n8n-u: n8n idempotency concurrency locking race conditions
# Zašto prebaciti pozadinski posao iz Next.js-a#
Serverless funkcije obično imaju tvrda ograničenja trajanja izvršavanja. Na Vercelu, funkcija može isteći daleko prije nego što spori third-party API odgovori ili se konverzija datoteke dovrši. Čak i na dugotrajnim Node serverima, zauzimanje web threadova povećava latenciju i troškove.
Pozadinska obrada je važna jer:
- Korisnici doživljavaju sve iznad 300 do 500 milisekundi kao tromo za interaktivne akcije, a iznad 2 sekunde kao jasno kašnjenje za većinu tokova.
- Ponovni pokušaji su neizbježni. Mreže pucaju. API-ji povremeno vraćaju
429i503. Bez reda i idempotencije, retry se pretvara u duplikate. - Exactly-once obrada je rijetko doslovna. Praktični cilj je exactly-once sporedni učinci kombiniranjem at-least-once dostave s idempotentnim handlerima.
🎯 Ključna poruka: Vaš Next.js zahtjev treba samo validirati input, staviti namjeru u red i brzo vratiti odgovor. Svi sporedni učinci pripadaju worker sustavu s perzistencijom, retryjima i idempotencijom.
# Pregled arhitekture#
Ovo je tok koji implementirate:
- 1Klijent zove Next.js rutu
POST /api/jobsda pokrene posao. - 2Next.js ubacuje redak posla u Postgres s ključem idempotencije.
- 3Next.js okida n8n putem webhooka s
jobIdi istim ključem idempotencije. - 4n8n preuzima (claim) posao, izvršava dugi zadatak i ažurira status posla.
- 5n8n radi callback prema Next.js-u
POST /api/jobs/:id/callbacks metapodacima rezultata. - 6UI polla
GET /api/jobs/:idili koristi vaš preferirani real-time sloj za prikaz statusa.
Komponente i odgovornosti#
| Komponenta | Odgovornost | Mora biti pouzdano u |
|---|---|---|
| Next.js API ruta | Validacija, autentikacija, enqueue posla, okidanje workflowa | Upisu stanja posla i provođenju idempotencije |
| Postgres tablica reda | Izvor istine za status posla, pokušaje, lockove | Jedinstvenosti, zaključavanju, uvidu u kvarove |
| n8n workflow | Izvršavanje workera, retryji, dead-lettering | Idempotentnoj obradi i sigurnim sporednim učincima |
| Callback endpoint | Finalne tranzicije stanja i signali za UI update | Autentikaciji callbackova i monotonim statusnim ažuriranjima |
ℹ️ Napomena: Webhookovi nisu red. Oni su okidač. Red je vaša tablica u bazi koja perzistira posao i omogućuje sigurne ponovne pokušaje.
# Model podataka: tablica reda koja podržava retryje i exactly-once učinke#
Minimalna tablica reda vrlo brzo postane produkcijska obveza. Trebaju vam polja za pokušaje, lockove, raspoređivanje, hvatanje grešaka i idempotenciju.
Predložena Postgres shema#
CREATE TABLE job_queue (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
type TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'queued',
payload JSONB NOT NULL DEFAULT '{}'::jsonb,
idempotency_key TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
attempts INT NOT NULL DEFAULT 0,
max_attempts INT NOT NULL DEFAULT 8,
run_at TIMESTAMPTZ NOT NULL DEFAULT now(),
locked_at TIMESTAMPTZ,
locked_by TEXT,
last_error TEXT,
completed_at TIMESTAMPTZ,
result JSONB
);
CREATE UNIQUE INDEX job_queue_idempotency_unique
ON job_queue (type, idempotency_key);
CREATE INDEX job_queue_runnable_idx
ON job_queue (status, run_at)
WHERE status IN ('queued', 'retry');Životni ciklus statusa#
| Status | Značenje | Sljedeće tranzicije |
|---|---|---|
queued | Spremno za izvršavanje | processing, retry, dead |
processing | Worker je preuzeo posao | completed, retry, dead |
retry | Prolazni pad, zakazano za kasnije | processing, dead |
completed | Uspješno završeno | terminal |
dead | Trajno neuspješno, zahtijeva pregled | terminal |
canceled | Zaustavio korisnik ili sustav | terminal |
⚠️ Upozorenje: Ne modelirajte retryje tako da ponovno ubacujete nove retke. Gubite povijest i rušite idempotenciju. Jedan logički posao treba ostati jedan redak.
# Korak 1: Enqueue iz Next.js-a uz ključ idempotencije#
Vaš enqueue endpoint treba biti brz i determinističan.
Kada generirati ključeve idempotencije#
Koristite ključ generiran na klijentu za akcije koje korisnik pokreće i gdje se događaju dvoklikovi. Na primjer, slanje računa ili export podataka. Ako se akcija inicira na serveru, generirajte ga u API ruti.
Dobar ključ je stabilan za isti logički zahtjev:
userId + operation + normalizirani inputi- ili client UUID spremljen za vrijeme trajanja akcije
Primjer Next.js rute#
// app/api/jobs/route.ts
import { NextResponse } from 'next/server';
import crypto from 'crypto';
export async function POST(req: Request) {
const body = await req.json();
const { type, payload } = body;
const userId = 'auth-user-id'; // replace with your auth
const rawKey = `${userId}:${type}:${JSON.stringify(payload)}`;
const idempotencyKey = crypto.createHash('sha256').update(rawKey).digest('hex');
// 1) Insert or fetch existing job by (type, idempotency_key)
// Use your DB client; shown as pseudocode calls.
const job = await db.jobQueue.upsertByIdempotency({
type,
idempotencyKey,
payload,
});
// 2) Trigger n8n webhook (fire-and-forget)
await fetch(process.env.N8N_WEBHOOK_URL!, {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-internal-secret': process.env.N8N_WEBHOOK_SECRET!,
},
body: JSON.stringify({ jobId: job.id, type, idempotencyKey }),
});
return NextResponse.json(
{ jobId: job.id, status: job.status },
{ status: 202 }
);
}UI obrazac#
UI treba tretirati start posla kao 202 Accepted i odmah renderirati komponentu statusa posla koja polla GET /api/jobs/:jobId.
To smanjuje pritisak na inicijalni zahtjev i izbjegava “spinner zauvijek” kvarove uzrokovane prekidom veze klijenta.
💡 Savjet: Vratite postojeći posao kad se koristi isti ključ idempotencije. Korisnici mogu refreshati stranicu i i dalje vidjeti ispravan status posla.
# Korak 2: Okidanje n8n-a putem webhooka, ali preuzimanje posla iz Postgresa#
Ne šaljite pune payloadove kroz webhookove kao izvor istine. Dostava webhooka može se duplicirati, stići izvan redoslijeda ili pasti. Koristite ga samo kao signal da probudi workera.
Vaš n8n webhook node treba prihvatiti jobId i zatim učitati i preuzeti (claim) posao iz Postgresa.
Zahtjevi za logiku preuzimanja (claim)#
Preuzimanje mora:
- Osigurati da samo jedan worker obrađuje posao u isto vrijeme
- Biti sigurno pod konkurentnim dostavama webhookova
- Dopustiti ponovnu obradu samo kad je status “runnable”
Tipičan pristup je jedan atomarni update:
- Promijeniti status iz
queuediliretryuprocessing - Postaviti
locked_atilocked_by - Povećati attempts
- Vratiti redak
Ako update zahvati nula redaka, drugi worker ga je već preuzeo ili je posao u terminalnom stanju.
# Korak 3: Implementacija worker workflowa u n8n-u#
U n8n-u strukturirajte workflow u jasne faze:
- 1Validirajte webhook secret.
- 2Preuzmite (claim) posao u Postgresu.
- 3Izvršite korake zadatka uz sigurne sporedne učinke.
- 4Označite kao completed ili zakažite retry.
- 5Kod trajnog pada, prebacite u dead-letter tok.
- 6Napravite callback prema Next.js-u s finalnim statusom.
Preporučeni nodeovi#
| Faza | n8n node type | Napomene |
|---|---|---|
| Trigger | Webhook | Validirajte secret header |
| Claim job | Postgres | Atomarni update koji vraća redak |
| Work | HTTP Request, Postgres, Code | Držite korake malima |
| Retry scheduling | Code + Postgres | Izračunajte backoff i ažurirajte redak |
| Dead-letter | Postgres + notification | Pošaljite Slack ili email |
| Callback | HTTP Request | Potpisujte callback zahtjeve |
Primjer atomarnog claim SQL-a#
UPDATE job_queue
SET status = 'processing',
locked_at = now(),
locked_by = $1,
attempts = attempts + 1,
updated_at = now()
WHERE id = $2
AND status IN ('queued', 'retry')
AND run_at <= now()
AND attempts < max_attempts
RETURNING *;U n8n-u, $1 može biti identifikator workera poput n8n-main-1, a $2 je dolazni jobId.
Ako se ne vrati nijedan redak, završite workflow uspješno. Taj ishod je očekivan kod duplikata.
# Korak 4: Exactly-once obrasci uz ključeve idempotencije#
U distribuiranim sustavima najčešće dobivate at-least-once delivery. Exactly-once učinci dolaze iz idempotencije i provjera stanja.
Slojevi idempotencije koje trebate implementirati#
| Sloj | Što sprječava | Kako |
|---|---|---|
| Enqueue idempotencija | Duplo kreiranje posla | Unique index na type plus idempotency_key |
| Worker claim | Konkurentnu obradu | Atomarni update na runnable statusima |
| Idempotencija side-effecta | Duple vanjske učinke | Idempotency key proslijeđen providerima ili lokalno spremljen |
| Callback idempotencija | Dupla statusna ažuriranja | Dopuštati samo “naprijed” tranzicije statusa |
Primjer: idempotentni vanjski pozivi#
Mnogi API-ji podržavaju idempotency keyeve, posebno sustavi za plaćanje i slanje poruka. Ako podržavaju, proslijedite ključ idempotencije posla.
Ako provider to ne podržava, spremite lokalno “zapis sporednog učinka” keyed istim ključem idempotencije prije izvođenja akcije.
Primjer, prije slanja emaila:
- Umetnite
email_send_logs jedinstvenim ključemjobId + template + recipient - Ako insert padne zbog jedinstvenosti, tretirajte kao već poslano
ℹ️ Napomena: Exactly-once je poslovna garancija, ne transportna garancija. Cilj je “nikad ne naplati dvaput” i “nikad ne pošalji dvaput”, čak i ako se workflow pokrene dvaput.
Za više o locking-u i race conditionima u n8n-u pročitajte: n8n idempotency concurrency locking race conditions
# Korak 5: Retry politike koje ne otope vaš sustav#
Retryji trebaju biti promišljeni. Slijepi trenutni retryji stvaraju “thundering herd” i mogu pojačati outage.
Praktični retry defaulti#
- Pokušaji: 5 do 8 za mrežne pozive
- Backoff: eksponencijalan s jitterom
- Odvojite prolazne od trajnih grešaka
- Poštujte
Retry-Afterheader kada je prisutan
Česta politika:
- Odgoda u sekundama:
min(900, 2^attempt * 5) + jitter - Ograničite na 15 minuta za interaktivne poslove, duže za batch poslove
Predstavite izračun kao kod u malom nodeu ili funkciji.
// n8n Code node
const attempt = $json.attempts || 1;
const base = Math.min(900, Math.pow(2, attempt) * 5);
const jitter = Math.floor(Math.random() * 5);
return [{ nextDelaySeconds: base + jitter }];Zatim ažurirajte posao:
UPDATE job_queue
SET status = 'retry',
run_at = now() + ($1 || ' seconds')::interval,
last_error = $2,
updated_at = now()
WHERE id = $3;⚠️ Upozorenje: Retryanje ne-idempotentnih operacija bez ključeva idempotencije je način kako dobijete duple naplate, duple emailove i dvostruka umanjenja zaliha.
# Korak 6: Dead-letter tokovi za poslove koji se trebaju zaustaviti#
Kad posao premaši maksimalan broj pokušaja ili padne s trajnom greškom, prestanite retryati i učinite problem vidljivim.
Što spremiti u dead-letter#
Minimalno:
jobId- poruku greške
- korak na kojem je palo ili kod greške
- snapshot payloada
- timestampove i attempts
U Postgresu postavite:
status = 'dead'completed_at = now()last_error = ...
Zatim obavijestite tim. Na primjer, pošaljite Slack s deep linkom prema vašem admin UI-ju.
Kada odmah dead-letterati#
Dead-letter bez retryja kad:
- Padne validacija inputa
- Padne autentikacija ili autorizacija
- Traženi resurs ne postoji
- Provider vrati deterministički kod “nikad neće uspjeti”
Ova razlika je razlog zašto biste trebali normalizirati greške u tip poput transient naspram permanent.
# Korak 7: Status callbackovi za sigurno ažuriranje UI-ja#
Polling je ok, ali polling radi samo ako je stanje točno. Najsigurniji obrazac je da n8n ažurira kanoničko stanje u Postgresu i zatim obavijesti vašu aplikaciju kroz callback koji također ažurira stanje.
Pravila za callback endpoint#
Vaš callback endpoint mora:
- Autentikacijom zaštititi zahtjeve pomoću shared secreta ili potpisa zahtjeva
- Biti idempotentan i monoton
- Nikad ne smije vraćati posao unatrag u statusu
- Prihvaćati callbackove samo za poslove u
processingiliretry
Primjer callback rute#
// app/api/jobs/[id]/callback/route.ts
import { NextResponse } from 'next/server';
export async function POST(req: Request, ctx: { params: Promise<{ id: string }> }) {
const { id } = await ctx.params;
const secret = req.headers.get('x-callback-secret');
if (secret !== process.env.N8N_CALLBACK_SECRET) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
const body = await req.json();
const { status, result, error } = body;
// Only allow terminal transitions
const updated = await db.jobQueue.updateStatusSafely({
id,
status,
result,
error,
});
if (!updated) {
return NextResponse.json({ ok: true, ignored: true }, { status: 200 });
}
return NextResponse.json({ ok: true }, { status: 200 });
}Sigurne tranzicije statusa#
Implementirajte guard za tranzicije u SQL-u. Primjer pravila:
processingmože ići ucompleted,retryilideadretrymože ići uprocessingilideadcompletedideadsu terminalni
To sprječava race conditione gdje kasni retry callback prepiše već dovršen posao.
💡 Savjet: Ako želite trenutna UI ažuriranja, objavite realtime event nakon updatea baze. Tablica reda je i dalje izvor istine.
# Korak 8: Primjer punog toka: posao izvoza datoteke#
Čest stvarni slučaj je export CSV-a ili PDF-a:
- Export može trajati 10 do 60 sekundi.
- Često treba rate-limited API pozive i retryje.
- Rezultat mora biti pohranjen i moguće ga je preuzeti.
Kako se posao ponaša#
- 1Korisnik klikne Export.
- 2Next.js stavlja posao u red s
type = export_csvi payloadom poput filtera i stupaca. - 3n8n ga preuzima i generira datoteku.
- 4n8n uploada datoteku u object storage.
- 5n8n postavlja
result = { url, expiresAt, bytes }i označava posao kao completed. - 6UI prikazuje “Download” kad status postane completed.
Primjer oblika rezultata#
| Polje | Tip | Primjer |
|---|---|---|
result.url | string | signed download URL |
result.expiresAt | string | ISO timestamp |
result.bytes | number | 204800 |
result.checksum | string | sha256 |
Ovo je pobjeda za korisničko iskustvo jer korisnik može napustiti stranicu i kasnije svejedno preuzeti export.
# Operativne napomene: konkurentnost, observability i trošak#
Kontrole konkurentnosti#
Ograničite konkurentnost na razini workera kako ne biste zagušili third-party API-je. U n8n-u možete:
- Pokrenuti više workera, ali ograničiti concurrency workflowa
- Koristiti database lock polje i poštovati ga
- Dodati per-provider rate limiting koristeći čekanje i raspoređivanje
Ako trebate naprednije obrasce poput outboxa i transakcijskih garancija između sustava, koristite ovu referencu: n8n Postgres queue outbox pattern reliable integrations
Logovi i metrike koje su važne#
Pratite ove metrike u bazi i na dashboardima:
- Broj kreiranih poslova po satu po tipu
- Postotak uspjeha i prosječno trajanje
- Stopa retryja i prosječan broj pokušaja
- Broj dead-letter poslova i top error kodovi
Zdrav sustav tipično ima:
- Nisku jednocifrenu stopu retryja u normalnim uvjetima
- Gotovo nulti dead-letter volumen za stabilne tokove
- Jasne spikeove tijekom provider outageova, nakon čega slijedi oporavak bez ručne intervencije
Osnove sigurnosti#
- Zaštitite webhook i callback endpointove shared secretima.
- Validirajte veličine i tipove payloada.
- Nikad ne dopustite klijentima da direktno postavljaju
status. - Čuvajte secreta u environment varijablama, ne u n8n workflow JSON-u.
# Česte zamke i kako ih izbjeći#
- 1
Tretiranje webhookova kao trajnog (durable) reda
Uvijek prvo perzistirajte poslove u Postgresu. Webhookovi mogu biti izgubljeni ili duplicirani. - 2
Retryanje bez idempotencije
Ako se korak može izvršiti dvaput, izvršit će se dvaput. Učinite side-effecte idempotentnima s unique constraintima ili provider keyevima. - 3
Ažuriranje UI-ja iz originalnog zahtjeva
Korisnici zatvaraju tabove i mreže pucaju. UI mora čitati status posla iz baze. - 4
Dopuštanje callbackovima da prepišu terminalna stanja
Nametnite monotone tranzicije. Kasni callbackovi su česti tijekom retryja.
Za širi kontekst o redovima i opcijama izvršavanja poslova u Next.js-u pogledajte: Next.js background jobs queues cron Vercel
# Ključne poruke#
- Perzistirajte svaki pozadinski posao u Postgres tablici reda i tretirajte je kao izvor istine, a ne webhook payload.
- Koristite ključ idempotencije s unique constraintom kako biste spriječili duple poslove i u praksi postigli exactly-once side-effecte.
- Preuzimajte poslove atomarnim updateom kako biste osigurali obradu od strane jednog workera čak i uz duple dostave webhooka.
- Implementirajte eksponencijalni backoff s jitterom, a trajne greške dead-letterajte umjesto da retryate zauvijek.
- Sigurno ažurirajte UI kroz status polling plus autentificirane callbackove koji nameću monotone tranzicije stanja.
# Zaključak#
Next.js je odličan za korisničke zahtjeve, ali dugotrajni zadaci pripadaju worker sustavu dizajniranom za retryje i kvarove. Uz n8n i red temeljen na Postgresu možete isporučiti pouzdanu pozadinsku obradu bez dodavanja punog message brokera prvog dana.
Ako želite pomoć pri implementaciji Next.js pozadinskih poslova s n8n u vašem proizvodu, uključujući dizajn reda, idempotenciju i produkcijsko učvršćivanje (hardening), kontaktirajte Samioda i pregledat ćemo vaš trenutni tok te isporučiti funkcionalnu, testabilnu postavu.
FAQ
Osnivač i senior developer u Samiodi. 8+ godina iskustva u izradi React, Next.js, Flutter i n8n rješenja za klijente diljem Europe.
Više iz kategorije Poslovna automatizacija
Sve →Dizajniranje SLA-ova i SLO-ova za n8n automatizacije: latencija, budžeti neuspjeha, alerting i eskalacija
Saznajte kako postaviti i instrumentirati mjerljive ciljeve pouzdanosti za n8n automatizacije uz workflow SLA/SLO-e, budžete pogrešaka, pragove alertova i on-call runbooke.
Jedini izvor istine s n8n: Master podaci, dvosmjerna sinkronizacija i rješavanje konflikata
Praktičan vodič za 2026. za izgradnju sustava zapisa (system of record) između CRM-a, naplate i produktnih baza podataka uz n8n — s pravilima vlasništva, tablicama mapiranja, dvosmjernom sinkronizacijom, deduplikacijom, rješavanjem konflikata te pouzdanim replay/backfill poslovima.
Sigurni odlazni webhookovi iz n8n-a: potpisivanje, ponovni pokušaji, idempotentnost i zaštita od replay napada
Praktični vodič za 2026. o sigurnosti n8n webhookova za odlazne pozive: potpisivanje zahtjeva, vremenske oznake i nonce, idempotency ključevi, sigurni ponovni pokušaji s backoffom, dead-letter obrada te verifikacija i deduplikacija na strani potrošača.
Trebate pomoć s projektom?
Gradimo prilagođena rješenja koristeći tehnologije iz ovog članka. Senior tim, fiksne cijene.
Povezani članci
Automatizacija vođena događajima s n8n: Webhookovi, redovi i pouzdani konzumenti
Izgradite n8n arhitekturu vođenu događajima s trajnim webhookovima, RabbitMQ ili Kafka redovima, ponovnim pokušajima, dead-letter obradom i idempotentnim konzumentima. Uključuje primjere događaja narudžbi, CRM ažuriranja i analytics pipelinea.
Jedini izvor istine s n8n: Master podaci, dvosmjerna sinkronizacija i rješavanje konflikata
Praktičan vodič za 2026. za izgradnju sustava zapisa (system of record) između CRM-a, naplate i produktnih baza podataka uz n8n — s pravilima vlasništva, tablicama mapiranja, dvosmjernom sinkronizacijom, deduplikacijom, rješavanjem konflikata te pouzdanim replay/backfill poslovima.
Sigurni odlazni webhookovi iz n8n-a: potpisivanje, ponovni pokušaji, idempotentnost i zaštita od replay napada
Praktični vodič za 2026. o sigurnosti n8n webhookova za odlazne pozive: potpisivanje zahtjeva, vremenske oznake i nonce, idempotency ključevi, sigurni ponovni pokušaji s backoffom, dead-letter obrada te verifikacija i deduplikacija na strani potrošača.