Webhooks

Event catalogue

Every event Flux sends, when it fires, and the object it carries in data.object.

Subscribing#

An endpoint receives the event types in its events list, or every type with ["*"], including types added later. Ignore types you don't handle. Every event arrives in the same envelope.

Reminder events

invoice.due_soon, invoice.overdue and enrollment.cycle_due fire only for organizations that have turned on invoice reminders in Flux. They're off by default.

Catalogue#

Event	When	data.object
`invoice.created`	An invoice was raised, in the app or through the API.	Invoice
`invoice.updated`	An invoice was edited in the app.	Invoice
`invoice.submitted`	The raiser resubmitted a returned invoice.	Invoice
`invoice.returned`	A reviewer returned the invoice to the raiser.	Invoice
`invoice.awaiting_final_approval`	The accountant approved it and final approval is needed.	Invoice
`invoice.approved`	The invoice is fully approved.	Invoice
`invoice.issued`	The invoice was emailed to the customer. Fires together with `invoice.approved`.	Invoice
`invoice.voided`	The invoice was voided.	Invoice
`invoice.due_soon`	Reminder: the invoice is due within the organization's “days before due”. Needs invoice reminders on.	Invoice
`invoice.overdue`	Reminder at each overdue stage (by default 1, 7 and 14 days). Needs invoice reminders on.	Invoice
`invoice.paid`	The invoice was paid online, or payment was confirmed in the app.	Invoice
`invoice.payment_review`	An online payment didn't satisfy the invoice, for example a short amount or a different currency. The invoice stays unpaid.	Invoice
`payment.initiated`	A checkout started.	Payment initiated
`payment.succeeded`	An online payment was verified and accepted.	Payment outcome
`payment.failed`	An online payment wasn't accepted: Paystack declined it, or the money didn't satisfy the invoice (then `problem` says why and `invoice.payment_review` follows).	Payment outcome
`payment.refunded`	A refund made in Paystack was recorded.	Payment refunded
`receipt.issued`	A receipt is available for a paid invoice.	Receipt
`customer.created`	A customer was created, in the app or through the API.	Customer (with contacts)
`customer.updated`	A customer changed.	Customer (with contacts)
`enrollment.started`	A customer was enrolled in a service.	Enrollment
`enrollment.ended`	An enrollment ended.	Enrollment
`enrollment.cycle_due`	A billing cycle's date arrived. Needs invoice reminders on. Flux doesn't raise an invoice for it.	Enrollment
`webhook.test`	Sent by the test endpoint or the Test button. Can't be subscribed to; it goes only to the endpoint tested.	Test

Invoices events#

`invoice.created`#

An invoice was raised, in the app or through the API. data.object: Invoice.

Example

invoice.created

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.created",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "awaiting_approval",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": null,
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.updated`#

An invoice was edited in the app. data.object: Invoice.

Example

invoice.updated

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.updated",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "awaiting_approval",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": null,
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.submitted`#

The raiser resubmitted a returned invoice. data.object: Invoice.

Example

invoice.submitted

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.submitted",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "awaiting_approval",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": null,
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.returned`#

A reviewer returned the invoice to the raiser. data.object: Invoice.

Example

invoice.returned

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.returned",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "returned",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": null,
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.awaiting_final_approval`#

The accountant approved it and final approval is needed. data.object: Invoice.

Example

invoice.awaiting_final_approval

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.awaiting_final_approval",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "awaiting_final_approval",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": null,
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.approved`#

The invoice is fully approved. data.object: Invoice.

Example

invoice.approved

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.approved",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "approved",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.issued`#

The invoice was emailed to the customer. Fires together with invoice.approved. data.object: Invoice.

Example

invoice.issued

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.issued",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "approved",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.voided`#

The invoice was voided. data.object: Invoice.

Example

invoice.voided

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.voided",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "voided",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.due_soon`#

Reminder: the invoice is due within the organization's “days before due”. Needs invoice reminders on. data.object: Invoice.

Example

invoice.due_soon

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.due_soon",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "approved",
      "overdue": false,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.overdue`#

Reminder at each overdue stage (by default 1, 7 and 14 days). Needs invoice reminders on. data.object: Invoice.

Example

invoice.overdue

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.overdue",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "approved",
      "overdue": true,
      "paymentStatus": null,
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.paid`#

The invoice was paid online, or payment was confirmed in the app. data.object: Invoice.

Example

invoice.paid

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.paid",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "paid",
      "overdue": false,
      "paymentStatus": "successful",
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": "2026-11-03T14:02:00",
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

`invoice.payment_review`#

An online payment didn't satisfy the invoice, for example a short amount or a different currency. The invoice stays unpaid. data.object: Invoice.

Example

invoice.payment_review

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "invoice.payment_review",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 5012,
      "number": "MAX-2026-0042",
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "status": "approved",
      "overdue": false,
      "paymentStatus": "amount_mismatch: paid NGN 858,500.00, invoice requires NGN 860,000.00",
      "invoiceType": "subscription",
      "periodStart": "2026-11-01T00:00:00",
      "periodEnd": "2026-11-30T00:00:00",
      "nextDueDate": "2026-12-01T00:00:00",
      "createdAt": "2026-11-01T09:00:00",
      "approvedAt": "2026-11-01T11:30:00",
      "dueDate": "2026-11-15T00:00:00",
      "paidAt": null,
      "subtotal": 800000.00,
      "discount": 0.00,
      "taxableNet": 800000.00,
      "vatAmount": 60000.00,
      "vatLabel": "VAT (7.5%)",
      "total": 860000.00,
      "lines": [
        {
          "serviceId": 7,
          "description": "Subscription — 3 entities (3 × 250,000.00)",
          "detail": "3 entities",
          "quantity": 3,
          "unitPrice": 250000.00,
          "amount": 750000.00
        },
        {
          "serviceId": 9,
          "description": "Onboarding",
          "detail": null,
          "quantity": 1,
          "unitPrice": 50000.00,
          "amount": 50000.00
        }
      ],
      "payments": null
    }
  }
}

Payments events#

`payment.initiated`#

A checkout started. data.object: Payment initiated.

Example

payment.initiated

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "payment.initiated",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "reference": "T12-MAX-2026-0042-K3P9QZ_1",
      "invoiceId": 5012,
      "invoiceNumber": "MAX-2026-0042",
      "channel": "paystack",
      "gateway": "platform",
      "platformFeeMinor": 96000
    }
  }
}

`payment.succeeded`#

An online payment was verified and accepted. data.object: Payment outcome.

Example

payment.succeeded

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "payment.succeeded",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "reference": "T12-MAX-2026-0042-K3P9QZ_1",
      "invoiceId": 5012,
      "invoiceNumber": "MAX-2026-0042",
      "channel": "paystack",
      "succeeded": true,
      "problem": null
    }
  }
}

`payment.failed`#

An online payment wasn't accepted: Paystack declined it, or the money didn't satisfy the invoice (then problem says why and invoice.payment_review follows). data.object: Payment outcome.

Example

payment.failed

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "payment.failed",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "reference": "T12-MAX-2026-0042-K3P9QZ_1",
      "invoiceId": 5012,
      "invoiceNumber": "MAX-2026-0042",
      "channel": "paystack",
      "succeeded": false,
      "problem": "paid NGN 858,500.00, invoice requires NGN 860,000.00"
    }
  }
}

`payment.refunded`#

A refund made in Paystack was recorded. data.object: Payment refunded.

Example

payment.refunded

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "payment.refunded",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "reference": "T12-MAX-2026-0042-K3P9QZ_1",
      "invoiceId": 5012,
      "invoiceNumber": "MAX-2026-0042",
      "amountMinor": 100000,
      "currency": "NGN"
    }
  }
}

Receipts events#

`receipt.issued`#

A receipt is available for a paid invoice. data.object: Receipt.

Example

receipt.issued

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "receipt.issued",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "invoiceId": 5012,
      "invoiceNumber": "MAX-2026-0042",
      "customerId": 812,
      "currency": "NGN",
      "amount": 860000.00,
      "paidAt": "2026-11-03T14:02:00"
    }
  }
}

Customers events#

`customer.created`#

A customer was created, in the app or through the API. data.object: Customer (with contacts).

Example

customer.created

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "customer.created",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 812,
      "externalRef": "ws_42",
      "customerType": "company",
      "name": "Leadway Group Plc",
      "legalName": "Leadway Group Plc",
      "companyName": "Leadway Group",
      "firstName": null,
      "lastName": null,
      "email": "finance@leadway.example",
      "phone": "+2348012345678",
      "address": "121 Funso Williams Ave, Lagos",
      "taxId": "12345678-0001",
      "vatNumber": "VAT-001",
      "rcNumber": "RC123456",
      "parentCustomerId": null,
      "regulatedEntityCount": 3,
      "defaultCurrency": "NGN",
      "defaultSettlementBankId": null,
      "contacts": [
        {
          "name": "Finance",
          "email": "finance@leadway.example",
          "phone": null,
          "isBillingPrimary": true,
          "ccOnInvoices": false
        },
        {
          "name": "CFO",
          "email": "cfo@leadway.example",
          "phone": null,
          "isBillingPrimary": false,
          "ccOnInvoices": true
        }
      ],
      "createdAt": "2026-11-01T10:20:00",
      "updatedAt": null
    }
  }
}

`customer.updated`#

A customer changed. data.object: Customer (with contacts).

Example

customer.updated

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "customer.updated",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 812,
      "externalRef": "ws_42",
      "customerType": "company",
      "name": "Leadway Group Plc",
      "legalName": "Leadway Group Plc",
      "companyName": "Leadway Group",
      "firstName": null,
      "lastName": null,
      "email": "finance@leadway.example",
      "phone": "+2348012345678",
      "address": "121 Funso Williams Ave, Lagos",
      "taxId": "12345678-0001",
      "vatNumber": "VAT-001",
      "rcNumber": "RC123456",
      "parentCustomerId": null,
      "regulatedEntityCount": 3,
      "defaultCurrency": "NGN",
      "defaultSettlementBankId": null,
      "contacts": [
        {
          "name": "Finance",
          "email": "finance@leadway.example",
          "phone": null,
          "isBillingPrimary": true,
          "ccOnInvoices": false
        },
        {
          "name": "CFO",
          "email": "cfo@leadway.example",
          "phone": null,
          "isBillingPrimary": false,
          "ccOnInvoices": true
        }
      ],
      "createdAt": "2026-11-01T10:20:00",
      "updatedAt": "2026-11-08T16:45:00"
    }
  }
}

Enrollments events#

`enrollment.started`#

A customer was enrolled in a service. data.object: Enrollment.

Example

enrollment.started

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "enrollment.started",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 31,
      "customerId": 812,
      "serviceId": 7,
      "amount": 250000.00,
      "billingCycle": "monthly",
      "nextBillingDate": "2026-12-01T00:00:00",
      "cycleDate": null,
      "enrolledFrom": "2026-10-01T00:00:00",
      "enrolledTo": null,
      "active": true
    }
  }
}

`enrollment.ended`#

An enrollment ended. data.object: Enrollment.

Example

enrollment.ended

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "enrollment.ended",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 31,
      "customerId": 812,
      "serviceId": 7,
      "amount": 250000.00,
      "billingCycle": "monthly",
      "nextBillingDate": "2026-12-01T00:00:00",
      "cycleDate": null,
      "enrolledFrom": "2026-10-01T00:00:00",
      "enrolledTo": "2026-12-31T00:00:00",
      "active": false
    }
  }
}

`enrollment.cycle_due`#

A billing cycle's date arrived. Needs invoice reminders on. Flux doesn't raise an invoice for it. data.object: Enrollment.

Example

enrollment.cycle_due

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "enrollment.cycle_due",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "id": 31,
      "customerId": 812,
      "serviceId": 7,
      "amount": 250000.00,
      "billingCycle": "monthly",
      "nextBillingDate": "2026-12-01T00:00:00",
      "cycleDate": "2026-11-01T00:00:00",
      "enrolledFrom": "2026-10-01T00:00:00",
      "enrolledTo": null,
      "active": true
    }
  }
}

Testing events#

`webhook.test`#

Sent by the test endpoint or the Test button. Can't be subscribed to; it goes only to the endpoint tested. data.object: Test.

Example

webhook.test

{
  "id": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "type": "webhook.test",
  "created": "2026-11-01T10:20:00.4121933Z",
  "data": {
    "object": {
      "endpointId": 3,
      "message": "Test event from Flux ERP"
    }
  }
}

Event objects#

Invoice and customer events carry the same objects the API returns (with payments: null on invoices). The others are below.

payment.initiated object#

A checkout started.

Field	Description
referencestring	Payment reference.
invoiceIdinteger	The invoice.
invoiceNumberstring	The invoice number.
channelstring	Always `paystack`.
gatewaystring	Payment mode: `platform` (Flux's Paystack account), `custom` (the organization's own) or `legacy` (the organization hasn't set up payments).
platformFeeMinorinteger (64-bit)	Flux's platform fee added to the amount the payer pays, in minor units (kobo or cents). 0 when there's none.

payment.succeeded / payment.failed object#

An online payment was verified with Paystack.

Field	Description
referencestring	Payment reference.
invoiceIdinteger	The invoice.
invoiceNumberstring	The invoice number.
channelstring	The payment channel.
succeededboolean	`true` on `payment.succeeded`, `false` on `payment.failed`.
problemstring · nullable	Why the money didn't satisfy the invoice, as text, such as `paid NGN 858,500.00, invoice requires NGN 860,000.00`. `null` on success, and when Paystack itself declined the payment. Display it; don't parse it.

payment.refunded object#

A refund was made in Paystack.

Field	Description
referencestring	Payment reference.
invoiceIdinteger	The invoice.
invoiceNumberstring	The invoice number.
amountMinorinteger (64-bit)	Amount refunded in minor units (kobo or cents).
currencystring	ISO currency code.

receipt.issued object#

A receipt is available. Same as the receipt object, without paymentMethod.

Field	Description
invoiceIdinteger	The paid invoice.
invoiceNumberstring	The invoice number.
customerIdinteger	The customer.
currencystring	ISO currency code.
amountnumber (decimal)	The invoice total.
paidAttimestamp · nullable	When it was paid. Server time, no offset.

Enrollment event object#

Sent with enrollment.* events. Unlike the enrollments endpoint, it includes the billing cycle.

Field	Description
idinteger	Enrollment id.
customerIdinteger	The customer.
serviceIdinteger	The service.
amountnumber (decimal)	The agreed amount, else the service's price.
billingCyclestring · nullable	How often the service is billed. One of `monthly`, `quarterly`, `half_yearly`, `yearly`.
nextBillingDatedate · nullable	The next billing date.
cycleDatedate · nullable	The billing date that arrived. Set only on `enrollment.cycle_due`.
enrolledFromdate	Start date.
enrolledTodate · nullable	End date.
activeboolean	Whether the enrollment is active.

webhook.test object#

Sent by the test endpoint and the Test button in the Flux app.

Field	Description
endpointIdinteger	The endpoint tested.
messagestring	Always `Test event from Flux ERP`.

Event catalogue

Subscribing#

Catalogue#

Invoices events#

invoice.created#

invoice.updated#

invoice.submitted#

invoice.returned#

invoice.awaiting_final_approval#

invoice.approved#

invoice.issued#

invoice.voided#

invoice.due_soon#

invoice.overdue#

invoice.paid#

invoice.payment_review#

Payments events#

payment.initiated#

payment.succeeded#

payment.failed#

payment.refunded#

Receipts events#

receipt.issued#

Customers events#

customer.created#

customer.updated#

Enrollments events#

enrollment.started#

enrollment.ended#

enrollment.cycle_due#

Testing events#

webhook.test#

Event objects#

payment.initiated object#

payment.succeeded / payment.failed object#

payment.refunded object#

receipt.issued object#

Enrollment event object#

webhook.test object#

`invoice.created`#

`invoice.updated`#

`invoice.submitted`#

`invoice.returned`#

`invoice.awaiting_final_approval`#

`invoice.approved`#

`invoice.issued`#

`invoice.voided`#

`invoice.due_soon`#

`invoice.overdue`#

`invoice.paid`#

`invoice.payment_review`#

`payment.initiated`#

`payment.succeeded`#

`payment.failed`#

`payment.refunded`#

`receipt.issued`#

`customer.created`#

`customer.updated`#

`enrollment.started`#

`enrollment.ended`#

`enrollment.cycle_due`#

`webhook.test`#