Back to News
Changelog

Structured status detail, smarter waitFor(), and four new webhook events

webhookssdkapi

Peppol statuses differ by jurisdiction: a French DGFiP lifecycle code says more than a generic delivered. Today the structured layer behind our status model reaches the public surface — additively, without touching anything you rely on.

What changed

  • detail on GET /v1/invoices and in the SDK. List items now carry an optional detail map — one entry per axis (platformFiscal, delivery, businessDisposition, settlement), each preserving the jurisdiction's native code and label (e.g. DGFiP 213 — "Rejetée") with its versioned codeSystem. The SDK (2.2.0) exposes it on SendResult and list rows, alongside the new rawStatus — the raw gateway status string kept even when the SDK coerces status to unknown.
  • SDK: waitFor() resolves on a passed terminal success. If the document reaches paid while you wait for an earlier progress status (say delivered), the promise now resolves with the real result instead of polling until a timeout error. Terminal failures (failed, rejected, no_action) still fail fast, and the terminal sets are now derived from the exported STATUS_PRECEDENCE table.
  • Three missing webhook events. invoice.partially_paid, invoice.under_query and invoice.conditionally_accepted now dispatch — these statuses previously updated the dashboard but never notified your endpoints. Wildcard (*) subscribers receive them automatically.
  • New opt-in event invoice.status_changed. One generic notification per status update, carrying the legacy status plus the full per-axis state and the structured detail. Opt-in by design: it is never matched by the * wildcard, so existing wildcard integrations keep getting exactly one event per status update.
  • Stable webhook event ids. Status events now carry a deterministic id derived from the underlying provider occurrence — a provider redelivery reproduces the same id, so your endpoint can deduplicate reliably.

Anything breaking?

No runtime breaking change: everything is additive and the /v1 status vocabulary is untouched. TypeScript users upgrading the SDK: the WebhookEventType union gains four members, so an exhaustive switch over it needs new cases. invoice.closed is now deprecated (it was never emitted) and will be removed at the next major.