Event Types

This page lists all webhook events available to merchant endpoints. Each event follows the {entity}.{action} naming convention.

For setup instructions, signature verification, and retry behavior, see the Webhooks guide.

Payment events

Event	Description
`payment.created`	A new payment has been created.
`payment.processing`	The payment has been sent to the provider for processing.
`payment.succeeded`	The payment completed successfully. If 3DS was performed, `data.threeDSResult` contains the authentication outcome.
`payment.failed`	The payment was declined by the provider. If 3DS was performed, `data.threeDSResult` contains the authentication outcome.
`payment.canceled`	The payment was voided before completion.
`payment.requires_action`	Customer action is needed (e.g. 3DS authentication). `data.action` contains the action details, including redirect URL and method.
`payment.requires_capture`	The payment has been authorized and is awaiting capture.
`payment.captured`	A previously authorized payment has been captured.
`payment.refunded`	The payment has been fully refunded.
`payment.partially_refunded`	A partial refund has been applied to the payment. `data` includes `refundedAmount` and `remainingAmount`.

Refund events

Event	Description
`refund.created`	A refund has been initiated.
`refund.succeeded`	The refund completed successfully.
`refund.failed`	The refund failed.

Checkout events

Event	Description
`checkout.session.created`	A new checkout session has been created.
`checkout.session.completed`	The checkout session completed (payment succeeded).
`checkout.session.expired`	The checkout session expired before completion.

Dispute events

Event	Description
`dispute.created`	A dispute (chargeback) has been opened.
`dispute.updated`	A dispute has been updated with new information.
`dispute.won`	The dispute was resolved in your favor.
`dispute.lost`	The dispute was resolved against you.

Payout events

Event	Description
`payout.created`	A payout to a third-party recipient has been initiated.
`payout.succeeded`	The payout completed successfully.
`payout.failed`	The payout failed.

Settlement events

Event	Description
`settlement.finalized`	Settlement finalized and financial statement ready for download.

Withdrawal events

Event	Description
`withdrawal.created`	A withdrawal request has been created.
`withdrawal.approved`	The withdrawal has been approved by the operator.
`withdrawal.rejected`	The withdrawal has been rejected by the operator. `data` includes `rejectionReason`.
`withdrawal.canceled`	The withdrawal has been canceled by the entity that created it.
`withdrawal.succeeded`	The withdrawal completed successfully.
`withdrawal.failed`	The withdrawal failed during execution at the provider.

Balance events

Event	Description
`balance.available`	Funds have transitioned from pending to available after the T+N holding period. `data` includes `amount`, `currency`, and `entityType`.
`balance.threshold_reached`	Your balance has reached a configured threshold (low balance alert).

The event.data field contains the resource object that triggered the event, scoped to your access level. For example, a payment.succeeded event includes the Payment object, and a refund.created event includes the Refund object.

Merchant endpoints receive a limited view: amount, currency, status, and total merchantFee. Fee decomposition (provider fee, tenant fee, platform fee, partner commission) and provider-level details (raw provider status, terminal ID, routing details) are not included in merchant webhook payloads. Tenant and platform endpoints receive progressively more detail.

Subscribing to events

When creating or updating a webhook endpoint, you specify which events to receive using the events array. You can use:

Exact event names: ["payment.succeeded", "refund.created"]
Wildcards by category: ["payment.*", "refund.*"] — receive all events in those categories.
All events: ["*"] — receive every event type listed on this page.

curl -X POST https://api.miracle.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/miracle",
    "events": ["payment.*", "refund.*", "dispute.*"]
  }'

You can also browse the available event types via the API:

curl https://api.miracle.com/v1/webhooks/event-types \
  -H "Authorization: Bearer sk_test_..."