Breeze uses a webhook to notify you when a payout page status / sub-status changes. This ensures your system always stays in sync without needing to poll the API.

Webhook Delivery

Webhooks are sent to the endpoint configured in your Breeze dashboard
Each webhook contains:
- An event type which is either PAYOUT_PAGE_STATUS_UPDATE or PAYOUT_PAGE_PENDING_STATUS_UPDATE
- The current details of the payout page
You should verify webhook signature to ensure authenticity

Status Change Events

You will receive a webhook whenever a payout page transitions between statuses

{
  "type": "PAYOUT_PAGE_STATUS_UPDATE",
  "data": {
    "id": "payout_page_57b1de5641ee73a3",
    "status": "CREATED",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "064143097e7640a798a4cc92742b1ba81",
    "releaseMethod": "AUTOMATIC",
    "merchant": {
      "id": "mch_mock_merchant",
      "livemode": false
    },
    "customer": {
      "email": "[email protected]"
    }
  },
  "signature": "EpNi5UT8GwAspqStOw9aAroZEVrWeIkTf5u+FTni5XM="
}

Sub-status Change Events

When a payout page is in PENDING, sub-status changes are also sent as webhook events under pendingStatus.

Example waiting for merchant release (PENDING_MERCHANT_RELEASE)

{
  "type": "PAYOUT_PAGE_PENDING_STATUS_UPDATE",
  "data": {
    "id": "payout_page_57b1de5641ee73a3",
    "status": "PENDING",
    "pendingStatus": "PENDING_MERCHANT_RELEASE",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "064143097e7640a798a4cc92742b1ba81",
    "releaseMethod": "AUTOMATIC",
    "merchant": {
      "id": "mch_mock_merchant",
      "livemode": false
    },
    "customer": {
      "email": "[email protected]"
    },
  },
  "signature": "u+7rYGaH9hLXkUb3vT/4YqOS+RClCTjcZ/EgHm6Z00Q="
}