SearchStart a task
Guides›developers
developers

Secure webhook handling for invoice status events

Verify signatures, timestamps, replay protection and status transitions for asynchronous authority or provider webhooks.

invoice webhook securitye invoice callback verificationwebhook replay protection

What it means

Invoice webhooks deliver asynchronous status changes and must be authenticated, replay-resistant and idempotent.

The receiver should acknowledge quickly and process durable events through a queue.

Implementation method

  1. 1
    Verify the signature over the exact raw body and timestamp.
  2. 2
    Reject stale timestamps and previously processed event IDs.
  3. 3
    Queue the verified event before returning success.
  4. 4
    Reconcile out-of-order events against the authority status when necessary.

Common mistakes

!
Parsing JSON before signature verification changes the signed bytes

Build an explicit control or test case for this condition.

!
Logging secrets or full sensitive invoice payloads

Build an explicit control or test case for this condition.

!
Trusting source IP as the only authentication factor

Build an explicit control or test case for this condition.

!
Applying status events without state-transition checks

Build an explicit control or test case for this condition.

Questions and answers

What HTTP status should a webhook receiver return?

Follow provider rules, but normally acknowledge only after the event is authenticated and durably accepted for processing.

What if events arrive out of order?

Use event timestamps/version fields and query the authoritative status before moving a document backward.

Can EInvoiceLab officially certify webhook processing?

No. EInvoiceLab can inspect, prepare and explain technical data, but official conformance, delivery or acceptance depends on the active authority, network, accredited provider and validation artefacts.

Should I keep the original structured file?

Yes. Preserve the original XML or JSON, its hash, every validation report and the final authority or network response. A readable PDF should not replace the source document.