How to Set Airparser Webhook Retries for Failed Invoices
You fix missing invoice data in Airparser by enabling webhook retries and making your endpoint ignore duplicate document IDs. Airparser retries failed deliveries automatically, but only if your endpoint returns a 5xx or times out rather than replying 200 with an error inside the body.
The first time this goes wrong it looks like Airparser simply skipped documents. It didn’t. Your receiver returned 200, Airparser logged success, and the invoice was gone.
Why do parsed invoices go missing after the webhook fires?
Three causes, in order of how often they hit:
- Your endpoint returns 200 on internal failure. A common pattern — catch the exception, reply OK, log it. Airparser treats that as delivered and never retries.
- The parsing finished before your downstream system was ready. A supplier’s invoice arrives at 3am, your ERP does a nightly lock, the write fails.
- Duplicate deduplication on your side. Two identical invoices from the same vendor get the same hash and the second write is dropped without a warning.
The first is fixable in ten minutes. The other two need a little design.
Step 1: Check what Airparser sends on each parse
Every parsed document fires a POST with a JSON body containing the document ID, the parsed fields as key-value pairs, the original file URL, and a timestamp. Content type is application/json, and the payload is flat unless your schema has nested sections.
Grab one raw payload first. Open the document in Airparser, go to the Webhook tab, and use Send test with a request bin in front of it. Read the actual keys rather than the docs — field names come from your template, so invoice_number might be Invoice Number with a space if you named the column carelessly.
Step 2: Configure retries on the webhook
In the webhook settings, set the retry policy. Airparser supports automatic retries on failure with an increasing delay; the default is a small number of attempts within a couple of hours, which is too short for a nightly-batch problem.
For invoice processing, aim for:
- Retry window of at least 12 hours, ideally 24
- At least 5 attempts spread across that window
- Timeout of 15-20 seconds so a hung endpoint does not hold the queue
Check the exact retry limits on your plan. The Free and Lite tiers cap webhook volume hard (Lite is roughly 100 documents a month), so a document that fails all retries still counts against quota.
Step 3: Return the right status codes
This is the part that actually decides whether retries help.
| Situation | Return |
|---|---|
| Document stored, all fields mapped | 200 |
| Already processed (duplicate) | 200 |
| Downstream DB unreachable | 503 |
| Field mapping exception | 422 |
| Auth token wrong | 401 |
Never return 200 for 503 or 422 cases. A 422 tells Airparser the payload is unusable, and it stops retrying, which is correct — retrying a bad mapping just wastes attempts. A 503 keeps the document in the retry queue.
Log the document ID on every response so you can reconcile later.
Step 4: Make the receiver idempotent
Retries mean duplicates. Build for them before you turn retries on.
Use the Airparser document ID as your upsert key rather than your own hash of the fields. Two genuinely different invoices can share a total and a date; the document ID is unique per parse.
In practice that means a database constraint on the external ID column, and an ON CONFLICT DO NOTHING (or equivalent) on write. If your ERP has no external ID field, keep a small mapping table — 50 lines of code that saves a quarter-end reconciliation.
Step 5: Backfill what already failed
Turning retries on does not resurrect documents that failed last week. Export the document list from Airparser filtered by status, compare against your ERP’s invoice count, and re-push the missing IDs with the Re-run webhook action on each document.
Do this in batches of 20 or so. Airparser rate-limits manual re-runs and firing 400 at once gets you throttled with partial results, which is worse than either.
What are Airparser’s practical limits for invoice volume?
Airparser pricing scales by document count, not by page count, and one PDF is one document even at 40 pages. The starter tiers sit around $39/month for a few hundred documents, with enterprise per-document pricing below that for high volume.
The real limit for invoice processing is schema changes. Each time a supplier adds a field, someone has to edit the template and re-test. A template with 30 fields drifts within a month. Keep templates narrow — split purchase invoices and utility bills into separate parsers — and this stays manageable.
Who this setup suits
Small finance and ops teams processing 100 to 2,000 invoices a month, especially where invoices arrive as PDFs from a long tail of suppliers with inconsistent layouts. The parser handles the layout variety; you handle the reliability layer once and it keeps working.
It fits badly if you need line-item-level accuracy across multi-page tables with merged cells. Airparser’s table extraction is decent on clean grids and unreliable on scanned, skewed pages. For those, OCR quality is the bottleneck, and no retry policy helps.
A fair criticism: there is no built-in dead-letter queue. Failed documents sit in the dashboard with a status but you have to poll the API to find them. Any serious setup needs a small cron job that pulls documents stuck in an error state once an hour.
Quick Summary
- Airparser retries webhooks only when your endpoint returns 5xx or times out, not when it returns 200 on an internal error.
- Set a 12-24 hour retry window with at least 5 attempts for invoice flows.
- Return 200 for success and duplicates, 503 for downstream outages, 422 for bad mappings.
- Use the Airparser document ID as the upsert key; retries will produce duplicates otherwise.
- Retries do not fix historical failures — re-run those webhooks in batches of 20.
- There is no dead-letter queue, so add a cron job that polls errored documents.
