Flowie
Guides

Receive invoices

Inbound documents arrive as document.received webhooks. Webhooks are the recommended path; polling is the fallback when you cannot expose an HTTPS endpoint.

1 · Subscribe once

curl -X POST …/v1/webhooks \
  -H "Authorization: Bearer $FLOWIE_KEY" \
  -d '{
    "url":"https://example.com/hooks/peppol",
    "events":["document.received","document.updated","lifecycle.updated"]
  }'

The full event catalogue is in the webhook reference.

2 · Verify the HMAC on delivery

Every delivery carries X-Flowie-Signature: t=<unix>,v1=<sha256-hex> over t + "." + raw_body. Compare in constant time, against the raw body — a re-serialised JSON body will not match — and reject anything older than five minutes. See signing & verification.

3 · Fetch the structured view

curl …/v1/documents/{id}/structured \
  -H "Authorization: Bearer $FLOWIE_KEY"

A flat, agent-friendly projection of the document — push it into your ERP, AP automation or warehouse. You can also pull the canonical UBL XML or a PDF rendering.

4 · Move the lifecycle along

Call POST /v1/documents/{id}/lifecycle as the invoice is reviewed, approved, disputed and paid. We report the transitions to the local regime (France PPF, Italy SDI) for you. On the French side, mind the difference between refusal (210) and technical rejection (213) — one is terminal.

Polling instead of webhooks

No public endpoint? Poll GET /v1/documents with direction=incoming. It is cursor-paginated: keep passing the returned cursor until hasMore is false, and never hard-code an offset.

curl "…/v1/documents?direction=incoming&limit=100" \
  -H "Authorization: Bearer $FLOWIE_KEY"

If you miss an event

Failed deliveries retry eight times over roughly 20 hours, then the webhook auto-pauses. You can replay any single event with POST /v1/events/{id}/replay, or acknowledge a backlog with POST /v1/events/ack. The retry schedule is in the webhook reference.

Next