# Webhook Events Reference

A complete reference of all webhook events sent by the Monato platform. For setup and delivery behaviour, see the [Webhooks guide](/products/directdebit/content/guides/api/webhooks).

## Event Structure

All events share the same top-level structure:

| Field | Type | Description |
|  --- | --- | --- |
| `event` | string | The event type identifier |
| `timestamp` | string | ISO 8601 datetime of when the event was generated |
| `data` | object | Event-specific payload |


## Charge Events

### `charge_result`

Sent when a charge reaches a final outcome — either after processing by the banking network, or after being canceled upstream by penny validation.

**Trigger:**

- The banking network returns a confirmation, decline, or cancellation for a charge, **or**
- A charge created with `inline_instrument` is `canceled` because penny validation returned `NO_MATCH` or `ERRORED`. See the [Penny Validation guide](/products/directdebit/content/guides/penny-validation#webhooks) for when this applies.


Note: a successful penny validation (`MATCHED`) does **not** emit a dedicated `charge_result` event on its own — the charge continues to processing and the normal `charge_result` fires later with the banking-network outcome.


```json
{
  "event": "charge_result",
  "timestamp": "2025-09-30T12:19:18.086265Z",
  "data": {
    "charge_id": "683b4a12-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "confirmed",
    "charge_reference": "subscription-0235"
  }
}
```

Example of a cancellation driven by penny validation:


```json
{
  "event": "charge_result",
  "timestamp": "2026-03-29T12:01:30.000000Z",
  "data": {
    "charge_id": "683b4a12-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "canceled",
    "charge_reference": "subscription-0235",
    "ownership_verification_result": "NO_MATCH",
    "ownership_verification_result_at": "2026-03-29T12:01:29.450000Z",
    "ownership_information": {
      "name": "JOHN DOE",
      "document_id": "DOEJ800101XYZ"
    }
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `charge_id` | UUID | The unique identifier of the charge |
| `charge_result` | string | `confirmed`, `declined`, or `canceled` |
| `charge_reference` | string / null | The merchant-assigned reference, if provided |
| `ownership_verification_result` | string / null | Penny validation outcome: `MATCHED`, `NO_MATCH`, `ERRORED`, or `null` when penny validation is not enabled or did not run for this charge |
| `ownership_verification_result_at` | string / null | ISO 8601 datetime when the penny validation result was recorded, or `null` when penny validation did not run |
| `ownership_information` | object / null | Beneficiary data returned by the CEP. `null` when the result is `ERRORED`, when penny validation is not enabled, or when it did not run for this charge |
| `ownership_information.name` | string | Account holder name as reported on the CEP |
| `ownership_information.document_id` | string | Account holder document ID as reported on the CEP |


For full status descriptions see [Charge Statuses](/products/directdebit/content/reference/charge-statuses).

### `charge_chargeback`

Sent when a customer's issuing bank processes a chargeback against a previously confirmed charge.

**Trigger:** A chargeback is received from the banking network.


```json
{
  "event": "charge_chargeback",
  "timestamp": "2025-11-15T09:00:00.000000Z",
  "data": {
    "charge_id": "683b4a12-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "chargeback",
    "charge_reference": "subscription-0235"
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `charge_id` | UUID | The unique identifier of the original charge |
| `charge_result` | string | Always `chargeback` for this event |
| `charge_reference` | string / null | The merchant-assigned reference of the original charge, if provided |


See [Chargebacks](/products/directdebit/content/chargebacks) for information on how chargebacks affect your balance.

## Instrument Events

### `instrument_ownership_verification_result`

Sent when penny validation completes for an instrument and it transitions to either `active` or `errored`.

**Trigger:** The platform finishes the automatic ownership verification process for an instrument, with a `MATCHED`, `NO_MATCH`, or `ERRORED` result. This event fires for **every** terminal outcome, regardless of whether validation succeeded or failed.


```json
{
  "event": "instrument_ownership_verification_result",
  "timestamp": "2025-09-29T20:05:00.000000Z",
  "data": {
    "instrument_id": "1208f1c1-71a9-4f44-95ac-4207d028a096",
    "instrument_reference": "customer-3482-primary",
    "ownership_verification_result": "MATCHED",
    "ownership_verification_result_at": "2025-09-29T20:04:58.200000Z",
    "ownership_information": {
      "name": "JANE DOE",
      "document_id": "DOEJ900101XYZ"
    }
  }
}
```

Example of an `ERRORED` result:


```json
{
  "event": "instrument_ownership_verification_result",
  "timestamp": "2025-09-29T23:05:00.000000Z",
  "data": {
    "instrument_id": "1208f1c1-71a9-4f44-95ac-4207d028a096",
    "instrument_reference": "customer-3482-primary",
    "ownership_verification_result": "ERRORED",
    "ownership_verification_result_at": "2025-09-29T23:04:59.000000Z",
    "ownership_information": null
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `instrument_id` | UUID | The unique identifier of the instrument |
| `instrument_reference` | string / null | The merchant-assigned reference, if provided |
| `ownership_verification_result` | string | `MATCHED`, `NO_MATCH`, or `ERRORED` |
| `ownership_verification_result_at` | string | ISO 8601 datetime when the penny validation result was recorded |
| `ownership_information` | object / null | Beneficiary data returned by the CEP. `null` when the result is `ERRORED` |
| `ownership_information.name` | string | Account holder name as reported on the CEP |
| `ownership_information.document_id` | string | Account holder document ID as reported on the CEP |


See the [Penny Validation guide](/products/directdebit/content/guides/penny-validation) for details on the verification process and its lifecycle.

## Delivery and Retries

If your endpoint does not return a `200` or `201` response, the platform retries delivery once per hour for up to 10 hours. After 10 failed attempts, the event is not re-delivered — query the API directly for the current resource state.

See the [Webhooks guide](/products/directdebit/content/guides/api/webhooks#event-delivery-and-retries) for full delivery behaviour details.