Skip to main content

Webhooks

To receive notifications about events related to your account, you need to set up a webhook. This automated messaging method uses HTTP callbacks: when an event occurs, the webhook sends an HTTP request with a defined payload to a user-specified URL.

When integrating with PaymentsAI, you might want your applications to receive events (webhook events) as they occur in your PaymentsAI accounts. These events enable your backend system to execute actions based on feedback from the PaymentsAI. To enable webhook events, you need to register webhook endpoints. After you register them, PaymentsAI can push event data to your application’s webhook endpoint when events happen in your PaymentsAI account. PaymentsAI uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object. Receiving webhook events is particularly useful when dealing with asynchronous events such as transaction being processed, or when a payment gateway is activated.

To set up a webhook, please follow the tutorial How to set up a webhook with a detailed, step-by-step instructions.

You can find all webhooks endpoints in the Webhooks API Documentation

Event overview​

Payments AI generates Event objects when interesting things happen in your account. These events are sent to your registered endpoint.

Event types​

  • Transaction - A transaction event is generated when a new payment is processed.
  • Gateway - A gateway event is generated when a payment gateway is activated, deactivated or updated.
  • Organization - An organization event is generated when an organization is activated, deactivated, deleted or updated.
  • Subscription - A subscription event is created when a subscription is activated.
type Event = {
  deduplicationId: string; // unique identifier for the event, used to prevent duplicate events
  type: string;
  organizationId: string;
  metadata: Transaction | Gateway | Organization | Subscription;
};

Additional information​

  • Event delivery behaviors - PaymentsAI doesn’t guarantee delivery of events in the order in which they’re generated, and your endpoint needs to handle delivery of events out of order.
  • Live and test mode - You might receive events from both live and tests mode in case you have registered a single endpoint for both environments.
  • Duplicated events - PaymentsAI guarantees at-least-once delivery of events, so you might receive duplicate events.
  • Asynchrounous processing - Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously.

API Documentation​

You can find all webhooks endpoints in the Webhooks API Documentation.