Webhook Events Reference

Revaly sends webhook events whenever a subscribed activity occurs within your account. Each event represents a specific point in the lifecycle of a transaction, refund, recovery, or retry.

This reference describes the structure of webhook events and the event types currently supported by Revaly.

Event Naming

Webhook event names follow a consistent resource.action pattern, where the resource identifies the object associated with the event and the action describes what occurred.

Examples:

transaction.succeeded
refund.failed
recovery.started
retry.scheduled

Event Structure

Every webhook event is delivered using the same envelope structure. Common event metadata is included at the top level, while the event-specific payload is contained within data.object.

All currently supported webhook events include a Transaction object in data.object. The event type identifies what occurred, while the payload contains the associated transaction details.

{
  "id": "evt_01JSZK9ABC...",
  "eventType": "transaction.succeeded",
  "createdAt": "2026-04-21T14:32:10Z",
  "eventVersion": "v2026-04-21",
  "revalyAccountId": "acct_...",
  "deliveryId": "dlv_...",
  "isTest": true,
  "data": {
    "objectType": "transaction",
    "object": {
      "...": "..."
    }
  }
}

Event Attributes

Field	Description
`id`	Stable event identifier. Use for deduplication.
`eventType`	The event that occurred.
`createdAt`	Timestamp when the event was created.
`eventVersion`	Schema version associated with the endpoint.
`revalyAccountId`	Revaly account associated with the event.
`deliveryId`	Unique delivery attempt identifier. Changes on retries.
`isTest`	Indicates whether the event originated from a production or test environment.
`data.objectType`	Type of object included in the payload.
`data.object`	Event-specific object data.

⚠️
Event Deduplication
Use id for deduplication. Do not use deliveryId, as a new delivery ID is generated each time an event is retried.

Supported Events

Revaly publishes webhook events for key moments in the transaction, refund, recovery, and retry lifecycles. When configuring a webhook endpoint, you can subscribe to the event types that are relevant to your integration.

The following sections describe each supported event and the circumstances under which it is generated.

Transaction Events

Event	Description
`transaction.succeeded`	Sent when a payment, authorization, or capture completes successfully.
`transaction.declined`	Sent when a transaction is declined by the payment processor.
`transaction.processing_failed`	Sent when processing fails due to a system or operational error rather than a processor decline.
`transaction.voided`	Sent when a transaction is voided before settlement.

Refund Events

Event	Description
`refund.succeeded`	Sent when a refund completes successfully.
`refund.failed`	Sent when a refund attempt fails.

Recovery Events

Event	Description
`recovery.started`	Sent when a recovery process begins.
`recovery.succeeded`	Sent when a recovery process successfully restores a payment.
`recovery.failed`	Sent when all recovery attempts have been exhausted.
`recovery.canceled`	Sent when a recovery process is canceled.

Retry Events

Event	Description
`retry.scheduled`	Sent when a retry attempt is scheduled.
`retry.executed`	Sent when a scheduled retry is executed.