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

# Event reference

> Complete webhook event payload reference.

## Payload envelope

All events share this structure:

```json theme={null}
{
  "id": "evt_a1b2c3d4e5f6789012345678abcdef01",
  "type": "invoice.paid",
  "createdAt": "2024-06-24T12:00:00.000Z",
  "data": {
    "invoice_id": "inv_a1b2c3d4e5f6789012345678abcdef01",
    "integration_id": "int_a1b2c3d4e5f6789012345678abcdef01",
    "external_order_id": "order_1048",
    "amount": "100.00",
    "expected_amount": "100.00",
    "received_amount": "100.00",
    "difference_amount": "0.00",
    "paid_amount": "100.00",
    "currency": "USD",
    "output_asset": "usdc",
    "tx_hash": "0x…",
    "paid_at": "2024-06-24T12:05:00.000Z",
    "payment_url": "https://pay.meum.io/inv_a1b2c3d4e5f6789012345678abcdef01",
    "status": "paid"
  }
}
```

<Note>
  Payloads use opaque public IDs (`inv_`, `evt_`, `int_`). Do not rely on undocumented fields if present in a response.
</Note>

## Standard merchant events

### invoice.created

Sent immediately after invoice creation. `data.status` is typically `awaiting_payment`.

### invoice.paid

Sent when full payment is validated. `data.paid_at` and `data.tx_hash` are populated.

### invoice.underpaid

Sent when partial payment detected. Check `difference_amount`.

### invoice.failed

Sent on payment failure.

### invoice.expired

Sent when invoice expires.

### invoice.cancelled

Sent when a merchant cancels an open invoice via `POST /v1/invoices/{id}/cancel`. Only invoices in open states (`awaiting_payment`, `quoted`, `pending`) can be cancelled. Terminal states (`paid`, `refunded`, etc.) cannot be cancelled.

<Info>
  Previously this event was subscribed on WooCommerce endpoints but not emitted. Public cancel API now dispatches `invoice.cancelled`.
</Info>

### webhook.test

```json theme={null}
{
  "id": "evt_demo_test",
  "type": "webhook.test",
  "data": { "message": "Test webhook from Meum" }
}
```

## Platform-emitted events (not in default subscriptions)

### invoice.refunded

<Warning>
  Not a standard merchant integration event. Do not assume this event is subscribed or delivered by default.
</Warning>

**When emitted:** Platform status polling detects a refund on an open invoice. The invoice status becomes `refunded` and `invoice.refunded` is dispatched.

**Not available:** Merchant-initiated refund API. Default WooCommerce managed webhook subscriptions do not include this event.

**WooCommerce behavior if received:** Adds an order note only; does not change order status.

## Expected HTTP response

Return **HTTP 200** with JSON body acknowledging receipt.

## Related pages

* [Verify signatures](/webhooks/verify-signatures)
* [Webhooks overview](/webhooks/overview)
* [Webhooks overview](/webhooks/overview)