Events & Webhooks

Outgoing webhooks are how PerfectPay pushes payment, refund, dispute, payout, and subscription updates to your systems.

Outgoing Payload Shape

Webhook payloads include top-level fields like these:

JSON

{
  "merchant_id": "merchant_123",
  "event_id": "evt_018e31720d1b7a2b82677d3032cab959",
  "event_type": "payment_succeeded",
  "content": {
    "type": "payment_details",
    "object": {}
  },
  "timestamp": "2026-03-22T15:12:00Z"
}

content is a typed envelope. Depending on the event, it carries payment, refund, dispute, mandate, payout, or subscription data.

Event Types

Payment Events

Event	Trigger
`payment_succeeded`	Payment completed successfully
`payment_failed`	Payment attempt failed
`payment_processing`	Payment is being processed
`payment_cancelled`	Payment was cancelled
`payment_captured`	Payment was captured (manual capture)
`payment_authorized`	Payment was authorized

Refund Events

Event	Trigger
`refund_succeeded`	Refund completed
`refund_failed`	Refund could not be completed

Dispute Events

Event	Trigger
`dispute_opened`	A dispute or chargeback was opened
`dispute_expired`	Dispute response window expired
`dispute_accepted`	Dispute was accepted
`dispute_cancelled`	Dispute was cancelled
`dispute_challenged`	Dispute was challenged
`dispute_won`	Dispute was resolved in your favor
`dispute_lost`	Dispute was resolved against you

Mandate Events

Event	Trigger
`mandate_active`	A mandate became active
`mandate_revoked`	A mandate was revoked

Webhook Delivery Flow

Loading diagram...

Configure Delivery

Configure outgoing webhooks from the dashboard. The business profile stores the webhook URL, response hash key, and custom outbound headers used for delivery.

Delivery Troubleshooting

Use the Events API when you need delivery history, attempt-level diagnostics, or a manual retry:

Endpoint	Purpose
`POST /events/{merchant_id}`	List events with filters such as `event_type` and `is_delivered`
`GET /events/{merchant_id}/{event_id}/attempts`	Inspect delivery attempts for a specific event
`POST /events/{merchant_id}/{event_id}/retry`	Manually retry delivery

Verification Guidance

PerfectPay signs webhook responses using the business profile's configured response hash key or webhook secret. Verify the signature before you fulfill an order or mutate internal state.

Operational Defaults

Treat deliveries as at least once
Deduplicate on event_id
Process asynchronously after basic validation
Keep your handler fast and idempotent