Skip to main content
POST
Accept Invoices

Authorizations

X-API-Key
string
header
required

Service API key. Required on every endpoint except /api/v1/health.

Headers

Idempotency-Key
string
required

Unique key for this webhook delivery, used for request tracing. Recommended to use a UUID. Maximum length 36 characters. Each delivery is scheduled as its own Cloud Task rather than deduplicated by this key -- see the response's task_id for why.

X-Organization-Id
string
required

Identifier of the organization/tenant that owns the invoices. Used for routing, logging, and idempotent task naming.

Body

application/json
invoices
WebhookInvoice · object[]

List of invoice payloads to process. A single request may contain up to 100 invoices; larger payloads will be rejected.

Maximum array length: 100

Response

Successful Response

status
enum<string>
required

Scheduling outcome for this webhook: 'scheduled' when a new Task is enqueued, 'duplicate' when Cloud Tasks reports a task name collision (practically unreachable in current usage, since each task_id includes a random per-call suffix), 'completed' (reserved for future use and not currently emitted), or 'error' when Cloud Tasks rejected the request.

Available options:
scheduled,
duplicate,
completed,
error
task_id
string
required

Cloud Tasks identifier for this delivery. Includes the organization and Idempotency-Key for traceability, but is suffixed with a random value per call -- it is not deterministic, so reusing the same Idempotency-Key across deliveries produces a different task_id each time and does not collide with (or get silently dropped in favor of) an earlier delivery.

scheduled_for
string<date-time>
required

UTC timestamp when the Task is scheduled to run.

idempotency_key
string
required

Opaque key supplied via the Idempotency-Key header, echoed back for correlation (max 36 chars). Does not deduplicate deliveries -- see task_id.

Required string length: 1 - 36
invoices_count
integer
required

Number of invoices accepted from the request payload.

received_at
string<date-time> | null

UTC timestamp when the webhook was received by the service.