> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice Webhooks

> The payload sent to your webhook endpoint when an invoice of invoice-based billing is finalized, sent, paid, past due, voided, or marked uncollectable.

> [!NOTE]
>
> Invoice webhooks apply to [invoice-based billing](https://docs.dodopayments.com/features/invoice-based-billing.md). Use them to keep the invoice status in your system the same as in Dodo Payments.

## Invoice Webhook Events

| Event | Fires when |
| - | - |
| `invoice.finalized` | An invoice is finalized. |
| `invoice.sent` | You send an invoice, Dodo Payments sends a renewal invoice, or the hosted link is first created. |
| `invoice.paid` | An invoice is paid, including a \$0 invoice at finalize. |
| `invoice.payment_failed` | An automatic charge fails. |
| `invoice.past_due` | An invoice becomes past due. |
| `invoice.reopened` | A past-due invoice becomes open after a due date change. |
| `invoice.voided` | An invoice is voided. |
| `invoice.marked_uncollectable` | An invoice is marked uncollectable. |

> [!NOTE]
>
> The payload shows the invoice at the time of delivery, not at the time of the event. Read `status` from the payload, and do not assume it from the event type.

## Handling Invoice Events

```javascript Handling invoice events expandable theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  // Verify the signature first. See /developer-resources/webhooks#verifying-signatures.
  const event = JSON.parse(req.body);
  const invoice = event.data;

  switch (event.type) {
    case 'invoice.paid':
      await markInvoicePaid(invoice.invoice_id, invoice.amount_paid);
      break;
    case 'invoice.past_due':
      await notifyAccountManager(invoice.invoice_id, invoice.amount_due);
      break;
    case 'invoice.voided':
    case 'invoice.marked_uncollectable':
      await closeInvoice(invoice.invoice_id, invoice.status);
      break;
  }

  res.json({ received: true });
});
```

> [!TIP]
>
> Refunds and disputes on invoice payments send the [refund](https://docs.dodopayments.com/developer-resources/webhooks/intents/refund.md) and [dispute](https://docs.dodopayments.com/developer-resources/webhooks/intents/dispute.md) events.

## Webhook Payload Schema


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.