# Processor Payout Events

Processor payout events are triggered throughout the lifecycle of payouts initiated on behalf of a specific processor. Unlike standard payouts, processor payouts are always processed in batches, allowing multiple payouts to be grouped and executed together.

GrailPay emits webhook events for each milestone in the processor payout process: when its transfer begins processing (`processor_payout.processing`), and when it completes or fails (`processor_payout.completed`, `processor_payout.failed`). These events enable your platform to monitor payout progress, reconcile processor-level transactions, and respond promptly to any issues that arise during processing.

All payloads below are shown in full, including the [event envelope](/docs/technical/webhooks/events/#event-envelope).

***

<!-- `processor_payout.created` is not emitted yet. Uncomment this section when it ships.
## `processor_payout.created`

This webhook is triggered when a processor payout is created.

```json title="Event"
{
  "event": "processor_payout.created",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```
-->
## `processor_payout.processing`

This webhook is triggered when the transfer for a processor payout has begun processing.

```json title="Event"
{
  "event": "processor_payout.processing",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```

## `processor_payout.failed`

This webhook is triggered when the transfer for a processor payout has failed.

```json title="Event"
{
  "event": "processor_payout.failed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```

## `processor_payout.completed`

This webhook is triggered when the transfer for a processor payout has completed.

```json title="Event"
{
  "event": "processor_payout.completed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```