Webhooks · Events
Webhook events
Outbound POS invoice webhooks are delivered to your organization's callback URL. You can inspect every delivery and retry one manually. The event catalogue, payload schema, and signatures are still being designed and are described under Coming soon.
Where webhooks are delivered
Webhooks are sent to the callBackUrl of your POS integration. Set it when you enable POS with POST /api/v1/organizations/pos/enable, or change it later with PATCH /api/v1/organizations/{orgReference}/pos/callback-url. The URL must use https. See API keys for the POS setup.
Inspect and retry deliveries
Each delivery attempt is recorded in a delivery log. Requests use your bearer token and the X-Client-Id header, and responses use the standard envelope.
GET /api/v1/organizations/{orgReference}/pos/webhooks
List delivery logs, paginated and filterable.
GET /api/v1/organizations/{orgReference}/pos/webhooks/{webhookId}
Fetch one delivery log.
POST /api/v1/organizations/{orgReference}/pos/webhooks/{webhookId}/retry
Manually retry a delivery. Returns the updated log.
The list endpoint accepts these query parameters.
page
integer · 0-based page number. Default 0.
size
integer · Page size, 1 to 100. Default 20.
sortBy
string · Default dateCreated.
sortDir
string · Default desc.
status
string · SUCCESS, FAILED, or PENDING.
search
string · Free-text search.
startDate, endDate
date · YYYY-MM-DD range filter.
Delivery log fields
id
string · Delivery log ID, used as webhookId.
organizationReference, organizationId
string · Organization the delivery belongs to.
invoiceId, reference
string · Invoice the delivery relates to, and its reference.
callbackUrl
string · URL the webhook was sent to.
event
string · Event name recorded for the delivery.
payload
string · Request body sent, stored as a string.
status
string · SUCCESS, FAILED, or PENDING.
attemptCount
integer · Number of delivery attempts.
responseCode
integer · HTTP status your endpoint returned.
responseBody
string · Response body your endpoint returned.
errorMessage
string · Why the attempt failed, when it did.
dateCreated, dateUpdated
date-time · When the log was created and last updated.
Delivery statuses
SUCCESS
Your endpoint accepted the delivery.
FAILED
The delivery did not succeed. Check responseCode and errorMessage, then retry.
PENDING
The delivery has not completed yet.
What the API does not define yet
The API does not document event names, the payload schema, an automatic retry schedule, request timeouts, or a signature. Treat the payload and event values in your logs as the source of truth, and use retry to redeliver a failed attempt. Respond with a 2xx quickly from your endpoint.
Coming soon: event catalogue and signed events Soon
Planned design, not live
Everything in this section previews the intended design. None of these event names, fields, headers, or behaviours exist in the API today. For signing, see Verify signatures.
Planned event envelope
id
string · Unique event ID, for example evt_demo_01
type
string · invoice.issued
created_at
datetime · 2026-09-23T15:24:10Z
data.object
object · Current invoice snapshot
delivery
object · Attempt metadata
Planned event types
invoice.created
A draft invoice is created.
invoice.issued
A draft is finalized and issued.
invoice.cancelled
An eligible invoice is cancelled.
delivery.succeeded
The recipient channel accepts the invoice.
delivery.failed
The delivery provider returns a terminal failure.
delivery.retry_scheduled
A retryable attempt is queued.
Planned headers
X-Webhook-Id
Event ID, for duplicate detection.
X-Webhook-Timestamp
Unix timestamp of the attempt.
X-Webhook-Signature
HMAC-SHA256 signature of the request.
Planned retry policy
Non-2xx responses and network timeouts would be retried automatically with increasing delay, and events could arrive more than once or out of order, so handlers should be idempotent.