Webhooks

Maroo can send webhook notifications to your server when events happen in your account. You configure webhook destinations via the Webhooks API, specifying a URL and optionally filtering by event type.

Each delivery is an HTTP POST request with a JSON body. The request includes signature headers so you can verify authenticity.

Envelope

Every webhook delivery has the same top-level structure:

JSON

{
  "id": "evt_d4f5a8b0-1c2e-4a6f-b8d0-3e5f7a9c1b2d",
  "type": "invoice.created",
  "apiVersion": "2026-05-01",
  "livemode": true,
  "createdAt": "2026-05-07T14:30:00.000Z",
  "data": { ... }
}

Field	Type	Description
id	string	Unique event identifier, prefixed with evt_.
type	string	The event type that triggered this delivery.
apiVersion	string	The API version used to render the payload.
livemode	boolean	true for production, false for sandbox.
createdAt	string	ISO 8601 timestamp of when the event was created.
data	object	Event-specific payload. Structure depends on type.

Event types

Invoice events

These events include the full invoice object in data.invoice.

Event type	Description
invoice.created	A new invoice was created.
invoice.updated	An invoice was updated (e.g. amount, payment methods, due dates).
invoice.sent	An invoice was sent to the recipient.
invoice.paid	All payments on an invoice are paid.
invoice.reopened	A previously paid invoice was reopened.

Invoice deleted event

Event type	Description
invoice.deleted	An invoice was deleted. Only the invoice id is included.

Payment events

These events fire when an individual payment within an invoice changes status. The payload includes data.invoiceId and data.payment.

Event type	Description
invoice.payment.processing	A payment started processing.
invoice.payment.completed	A payment completed successfully.
invoice.payment.failed	A payment failed.
invoice.payment.marked_as_paid	A payment was manually marked as paid.
invoice.payment.unmarked_as_paid	A "marked as paid" status was removed from a payment.

Payloads

Invoice events

Events invoice.created, invoice.updated, invoice.sent, invoice.paid, and invoice.reopened share this payload shape:

JSON

{
  "invoice": {
    "id": "d4f5a8b0-1c2e-4a6f-b8d0-3e5f7a9c1b2d",
    "contactId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "status": "Active",
    "deliveryMethod": "Email",
    "paymentLink": "https://pay.maroo.us/acme/abc123",
    "enableAutoreminders": true,
    "note": "First milestone payment",
    "ccEmails": ["[email protected]"],
    "paymentMethods": ["BankAccount", "CreditCard"],
    "paymentSchedule": [
      {
        "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
        "dueDate": "2026-06-01",
        "name": "Deposit",
        "amount": 50000,
        "status": "Scheduled",
        "paymentDate": null,
        "fee": null
      }
    ],
    "totalAmount": 50000
  }
}

Field	Type	Description
invoice.id	string	Invoice ID.
invoice.contactId	string | null	Client contact ID, if linked.
invoice.status	string	Draft or Active.
invoice.deliveryMethod	string	Email or PaymentLink.
invoice.paymentLink	string | null	Payment link URL. Null for draft invoices.
invoice.enableAutoreminders	boolean	Whether automatic reminders are enabled.
invoice.note	string | null	Note attached to the invoice.
invoice.ccEmails	string[]	CC email addresses.
invoice.paymentMethods	string[]	Accepted payment methods: DebitCard, CreditCard, BankAccount, Check.
invoice.paymentSchedule	object[]	List of payments in the invoice.
invoice.paymentSchedule[].id	string	Payment ID.
invoice.paymentSchedule[].dueDate	string	Due date (YYYY-MM-DD).
invoice.paymentSchedule[].name	string | null	Payment name (e.g. "Deposit").
invoice.paymentSchedule[].amount	integer	Amount in minor currency units.
invoice.paymentSchedule[].status	string	Payment status (see Payment statuses).
invoice.paymentSchedule[].paymentDate	string | null	ISO 8601 date when paid, or null.
invoice.paymentSchedule[].fee	integer | null	Processing fee in minor units, or null.
invoice.totalAmount	integer	Sum of all payment amounts in minor currency units.

Invoice deleted event

The invoice.deleted event contains only the invoice ID:

JSON

{
  "invoice": {
    "id": "d4f5a8b0-1c2e-4a6f-b8d0-3e5f7a9c1b2d"
  }
}

Payment events

Events invoice.payment.processing, invoice.payment.completed, invoice.payment.failed, invoice.payment.marked_as_paid, and invoice.payment.unmarked_as_paid share this payload shape:

JSON

{
  "invoiceId": "d4f5a8b0-1c2e-4a6f-b8d0-3e5f7a9c1b2d",
  "payment": {
    "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
    "dueDate": "2026-06-01",
    "name": "Deposit",
    "amount": 50000,
    "status": "Processing",
    "paymentDate": null,
    "fee": null
  }
}

Field	Type	Description
invoiceId	string	ID of the invoice this payment belongs to.
payment.id	string	Payment ID.
payment.dueDate	string	Due date (YYYY-MM-DD).
payment.name	string | null	Payment name.
payment.amount	integer	Amount in minor currency units.
payment.status	string	Payment status (see Payment statuses).
payment.paymentDate	string | null	ISO 8601 date when paid, or null.
payment.fee	integer | null	Processing fee in minor units, or null.

Payment statuses

Status	Description
Draft	Invoice is in draft; payment not yet active.
Scheduled	Payment is scheduled for a future due date.
Due	Payment is due today.
PastDue	Payment is past its due date.
Processing	Payment is being processed.
Paid	Payment completed successfully.
Failed	Payment processing failed.
MarkedAsPaid	Payment was manually marked as paid.
Blocked	Payment is blocked.
Authorization	Payment authorization is in progress.
Pending	Payment is pending.
Accepted	Payment was accepted.
Declined	Payment was declined.
PaidByGuest	Payment was made by a guest (not the primary contact).
Expired	Payment has expired.
Submitted	A refund has been submitted for this payment.
Refunded	Payment was refunded.