Skip to main content
VTPE sends webhook events to notify your system about payment lifecycle changes. Your webhook handler receives all events at a single endpoint and must acknowledge each one with an HTTP 200 response. This page covers the common headers, envelope format, retry behavior, and the full event catalog.

​
Webhook Request Headers

Every webhook request includes these headers.

​
Event Envelope

All webhook events share the same envelope structure:
The event field identifies the event type, and the data object contains event-specific fields.

​
Retry Behavior

VTPE retries delivery when your endpoint returns any non-2xx status code. To avoid duplicate processing, you should:
  • Return HTTP 200 as soon as you validate and queue the event.
  • Implement idempotency checks using paymentId before performing any business action.
  • Process events asynchronously when possible to minimize response latency.

​
Acknowledging Events

Acknowledge every webhook event by returning HTTP 200 with this JSON body:
If VTPE does not receive a 200 response, it will retry delivery.

​
Event Catalog

payment.initialized

Sent when a payment session is created for a reference.

payment.success

Sent when a payment is successfully confirmed.

payment.fail

Sent when a payment fails or is cancelled.
Always verify webhook signatures before trusting the payload. See the Webhook Security guide for implementation details.