Skip to main content
Webhooks are a way to receive notifications from HelloPay when certain events occur. Our platform will send a POST request to the URL you provide when certain events occur and retry sending the request every hour until it is successful or the 10th retry is reached. Any 2xx response code will be considered successful and the request will be considered delivered.

​
How to setup webhooks

  1. Enter the HelloPay portal. (Staging | Production)
  2. Go to “Settings -> Webhooks”. (Staging | Production)
  3. Fill in the configuration details.
  4. Save your webhook configuration.
Note: As you will notice, we require that you provide an authentication header. Currently this is in the only method we support.

​
Events

The events’ payload are in JSON format. Find below the spec:

​
Payins

{
  event: 'payin.processing' | 'payin.confirmed' | 'payin.canceled' | 'payin.declined';
  resource: 'payin';
  data: {
    id: string;
    reference: string | null;
    amount: number;
    currency: 'COP';
    status: 'PROCESSING' | 'CONFIRMED' | 'CANCELED' | 'DECLINED';
    rail: 'BRE_B' | 'PSE';
    sourceData: object;
    errorCode: string | null;
    createdAt: Date;
    updatedAt: Date;
    resultAt: Date | null;
    organizationId: string;
  };
}

​
Payouts

{
  event: 'payout.processing' | 'payout.confirmed' | 'payout.canceled' | 'payout.declined';
  resource: 'payout';
  data: {
    id: string;
    reference: string | null;
    amount: number;
    currency: 'COP';
    status: 'PROCESSING' | 'CONFIRMED' | 'CANCELED' | 'DECLINED';
    rail: 'BRE_B';
    targetData: object;
    errorCode: string | null;
    createdAt: Date;
    updatedAt: Date;
    resultAt: Date | null;
    organizationId: string;
  };
}
Fired when a payment link is settled. paymentlink.completed is sent when the payer successfully pays; paymentlink.expired is sent when the 1-hour window elapses without a successful payment. See Payment links for full context. 
{
  event: 'paymentlink.completed' | 'paymentlink.expired';
  resource: 'paymentlink';
  data: {
    paymentLinkId: string; // UUID
    reference: string | null;
    amount: number;
    currency: 'COP';
    status: 'COMPLETED' | 'EXPIRED';
    createdAt: Date;
    updatedAt: Date;
    expiresAt: Date | null;
    completedAt: Date | null;
  };
}
A successful payment on a payment link can also be detected via the payin.confirmed event on the underlying payin. You do not need to listen to both — choose whichever fits your integration.