Webhooks

Webhooks let your server receive real-time notifications when events happen in your PaymentsAI account. PaymentsAI sends an HTTP POST request to your registered endpoint whenever an event occurs. No polling is required.

What's in this section

Page	What it covers
Overview	How webhooks work, event envelope, HMAC signature verification, delivery guarantees.
Event catalog	All subscribable event types with descriptions of when each fires.
Schemas	TypeScript type definitions for every payload object (Transaction, Subscription, Dispute, and their nested types).
Best practices	Deduplication, async processing, ordering, replay protection.
Testing webhooks	Local testing with ngrok, replaying events from the dashboard, common errors.

Quick start

Register a destination and start receiving events in three steps:

1. Register your endpoint

curl -X POST "https://staging-api.payments.ai/v1/webhook-destinations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://your-server.com/webhooks",
        "auth": {
          "type": "basic",
          "username": "user",
          "password": "pass"
        }
      }'

2. Subscribe to event types

Pass eventTypes when registering, or update an existing destination. Example: subscribe to all transaction events:

{
  "eventTypes": ["transaction-processed", "transaction-declined"]
}

See Event catalog for all available values.

3. Handle the delivery

Respond with HTTP 200 immediately. Process the payload asynchronously. Verify the signature header on every request. See Overview for verification code examples.

Full API reference

All webhook endpoint operations are documented in the Webhooks API Documentation.