# 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 whenever a charge reaches a final outcome. This includes confirmation, decline, cancellation, and chargebacks — there is no separate event type for chargebacks.

**Triggers:**

- The banking network returns a result for a charge
- Penny validation cancels a charge (runs before risk verification)
- The risk engine cancels a charge (runs after penny validation)


All `charge_result` events include the same set of fields. Fields unrelated to the specific outcome are present but set to `null`.

**Confirmed charge**


```json
{
  "event": "charge_result",
  "timestamp": "2026-03-29T12:01:30.000000Z",
  "data": {
    "charge_id": "683b4a12-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "confirmed",
    "charge_reference": "subscription-0235",
    "debt_id": null,
    "declined_reason": null,
    "risk_status": "ok",
    "risk_reason": null,
    "ownership_verification_result": "matched",
    "ownership_verification_result_at": "2026-03-29T11:58:10.000000Z",
    "ownership_information": {
      "name": "JOHN DOE",
      "document_id": "DOEJ800101XYZ"
    }
  }
}
```

**Declined charge — insufficient funds**


```json
{
  "event": "charge_result",
  "timestamp": "2026-03-29T12:01:30.000000Z",
  "data": {
    "charge_id": "a1b2c3d4-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "declined",
    "charge_reference": "subscription-0236",
    "debt_id": null,
    "declined_reason": "insufficient_funds",
    "risk_status": "ok",
    "risk_reason": null,
    "ownership_verification_result": null,
    "ownership_verification_result_at": null,
    "ownership_information": null
  }
}
```

**Canceled charge — penny validation failed**


```json
{
  "event": "charge_result",
  "timestamp": "2026-03-29T12:01:30.000000Z",
  "data": {
    "charge_id": "b2c3d4e5-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "canceled",
    "charge_reference": "subscription-0237",
    "debt_id": null,
    "declined_reason": null,
    "risk_status": null,
    "risk_reason": null,
    "ownership_verification_result": "no_match",
    "ownership_verification_result_at": "2026-03-29T12:01:29.450000Z",
    "ownership_information": {
      "name": "JOHN DOE",
      "document_id": "DOEJ800101XYZ"
    }
  }
}
```

**Canceled charge — risk engine**


```json
{
  "event": "charge_result",
  "timestamp": "2026-03-29T12:01:30.000000Z",
  "data": {
    "charge_id": "c3d4e5f6-ebf9-40c2-9226-f97f4b7782ab",
    "charge_result": "canceled",
    "charge_reference": "subscription-0238",
    "debt_id": null,
    "declined_reason": null,
    "risk_status": "cancelled_by_risk",
    "risk_reason": ["instrument_chargeback_history"],
    "ownership_verification_result": null,
    "ownership_verification_result_at": null,
    "ownership_information": null
  }
}
```

#### Field Reference

| Field | Type | Value |
|  --- | --- | --- |
| `charge_id` | UUID | The unique identifier of the charge |
| `charge_result` | string | `confirmed`, `declined`, `canceled`, or `chargeback` |
| `charge_reference` | string / null | The merchant-assigned reference, if one was provided on the charge. For Collection as a Service charges, this is set to the `debt_id` |
| `debt_id` | string / null | The merchant-assigned debt identifier when the charge belongs to a [Collection as a Service](/products/directdebit/content/guides/collection-as-a-service) portfolio. `null` for standard charges |
| `declined_reason` | string / null | Platform-level decline code. Set when `charge_result` is `declined`. See [Error Codes](/products/directdebit/content/reference/error-codes#platform-error-codes) |
| `risk_status` | string | `ok` when the risk engine approved the charge; `cancelled_by_risk` when the risk engine blocked it |
| `risk_reason` | array / null | List of risk rules that triggered cancellation when `risk_status` is `cancelled_by_risk`; `null` otherwise. Possible values: `instrument_chargeback_history`, `bank_blacklist` |
| `ownership_verification_result` | string / null | `matched`, `no_match`, or `errored` when penny validation ran for this charge; `null` otherwise |
| `ownership_verification_result_at` | string / null | ISO 8601 datetime when penny validation completed; `null` when it did not run |
| `ownership_information` | object / null | Beneficiary data returned by the CEP when penny validation result is `matched`; `null` otherwise |
| `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). For chargeback handling see [Chargebacks](/products/directdebit/content/chargebacks).

## 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.