Events: invoice.*

Invoice events track a merchant’s one-off or ad-hoc invoices through their lifecycle. All three fire via the merchant fan-out path — every API key on the merchant with webhooks enabled and the matching event subscribed receives its own signed delivery.

Type	Fires when
invoice.created	An invoice was raised for a member (draft created).
invoice.sent	An invoice was issued / sent to the member.
invoice.paid	An invoice was settled.
invoice.voided	Reserved. The type is subscribable and returned by GET /api/Webhooks/event-types, but no delivery is emitted today. Don’t build logic that depends on receiving it.

Headers

Same envelope as other events: Topiic-Event-Id, Topiic-Idempotency-Key, Topiic-Signature. See Verifying signatures.

Bodies

The shared data core is the same across all three; invoice.sent adds sentAt, and invoice.paid adds transactionId + paidAt.

invoice.created

{
  "id": "c1a2b3d4-…",
  "type": "invoice.created",
  "createdAt": "2026-07-02T08:00:00.000Z",
  "merchantId": "e7d2f1a8-9c4b-4d62-8a3f-1b5c7e9d0f24",
  "data": {
    "invoiceId":      "5f6e7d8c-9b0a-1c2d-3e4f-5a6b7c8d9e0f",
    "invoiceNumber":  "INV-2026-000431",
    "memberId":       "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "subscriptionId": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "externalRef":    "cust_42",
    "amount":         49.50,
    "currency":       "AUD",
    "status":         "Draft"
  }
}

invoice.sent

Adds sentAt:

{
  "type": "invoice.sent",
  "data": {
    "...":     "(same core fields as invoice.created)",
    "status":  "Sent",
    "sentAt":  "2026-07-02T08:05:11.000Z"
  }
}

invoice.paid

Adds transactionId (the approved charge that settled it, if any) and paidAt:

{
  "type": "invoice.paid",
  "data": {
    "...":           "(same core fields as invoice.created)",
    "transactionId": "4d8c2a14-7b3d-4e9c-8d6f-1a2b3c4d5e6f",
    "status":        "Paid",
    "paidAt":        "2026-07-04T09:12:44.000Z"
  }
}

data fields

Field	Type	Notes
invoiceId	UUID	The Topiic Invoice id.
invoiceNumber	string	Human-facing invoice number.
memberId	UUID | null	The member the invoice is for, if any.
subscriptionId	UUID | null	The subscription the invoice relates to, if any.
externalRef	string | null	Your own id for the member (from the deep link’s ref), if one was recorded.
amount	decimal	Invoice total.
currency	string	ISO-4217 code (usually "AUD").
status	string	Invoice status at the time of the event ("Draft", "Sent", "Paid").
sentAt	ISO-8601 UTC	Present on invoice.sent. When the invoice was issued.
transactionId	UUID | null	Present on invoice.paid. The approved transaction that settled the invoice, if one exists.
paidAt	ISO-8601 UTC	Present on invoice.paid. When it was marked paid.

What to do on receipt

1. Verify the signature, dedupe on event.id.
2. Find the customer on your side via memberId or externalRef.
3. Mirror the invoice status into your own billing view; on invoice.paid, record transactionId against your receipt log.
4. Return 2xx within 10 seconds.

Note

These are separate from the subscription recurring-charge events. A payment.succeeded reflects a card charge; an invoice.paid reflects an invoice being settled (which may or may not have an associated transaction). Reconcile on transactionId when both are present.