​
Getting Response callbacks

One of the key benefits of getting humans to oversee your AI Agents is collaboration and oversight for spend.

In order to support this we’ve made it easy to register a webhook for your AI Agent to receive callbacks when spends are approved or rejected.

​
Quick Setup

  1. Create an endpoint to receive webhook events

  2. Go to your Agent Profile in the Payman dashboard

  3. Add your webhook URL

    Add webhook URL to the webhook field

Now anytime a noteworthy event takes place, a payload will be sent and your AI Agent will be able to action off of it.

​
Callback Payload

The webhook endpoint you specify must support POST requests. The body recieve will be this format:

{
    "eventType": "customer-deposit.successful",
    "details": {
        "customerId": "user_123",
        "amount": 100,  // 1 USD (returned in cents)
        "currency": "USD",
        "metadata": {       // Your custom data from the original request
            "sessionId": "abc123",
            "userId": "user_456"
        }
    }
}

​
Event Types

type WebhookEvent = {
  eventType: EventType;
  details: EventDetails;
};

enum EventType {
  // Customer Deposits
  WALLET_CUSTOMER_DEPOSIT_PENDING = "customer-deposit.pending",
  WALLET_CUSTOMER_DEPOSIT_SUCCESS = "customer-deposit.successful",
  WALLET_CUSTOMER_DEPOSIT_FAILURE = "customer-deposit.failed",

  // Balance Alerts
  BALANCE_LOW_WARNING = "balance.low", // sent at 50% of your highest balance

  // Payment Requests
  PAYMENT_REQUEST_APPROVED = "approval-request.approved",
  PAYMENT_REQUEST_REJECTED = "approval-request.rejected",
  PAYMENT_REQUEST_FAILED = "approval-request.failed",
}

​
Details Structure

The contents of the “details” object will depend somewhat on the type of event being received, but will contain one or more of the following:

"eventType": <eventType>
"details": {
  "customerId": "user_123", (applies only to customer-deposit.* events)
  "amount": 100,  // 1 USD (in cents) (applies only to customer-deposit.* events)
  "currency": "USD",
  "reason": "xxxx", // (only returned in customer-deposit.failed events)
  "balance": "100", // (applies only to balance.low events)
  "metadata": {       // Your custom data from the original request
      "sessionId": "abc123",
      "userId": "user_456"
  }
}

​
Metadata [Pro Tip]

When an agent takes an action (e.g. send payment or generate a customer link), it is possible to send along a metadata data property, which can be any JSON object. This metadata will be returned with any corresponding webhook callbacks as a metadata property of the details payload.

This can be very useful for correlating webhook callbacks with the customer or action in your system. For example you might send the user ID of the user who triggered the deposit on your system, or the session ID (or thread ID) associate with the run of your agent system.

const depositLink = await payman.payments.initiateCustomerDeposit({
  customerId: "user_123",
  amount: "1.0",
  metadata: {
    sessionId: "abc123",
    orderId: "order_789",
  },
});
Funding Sources