Webhook

Webhook notifications allow you to receive real-time updates about payment transaction status changes. When a payment's status changes (e.g., from pending to authorised, or from authorised to waiting), Hello Clever will send a POST request to your specified webhook endpoint.

Webhook Object

When a payment status changes, you'll receive a webhook notification with the following object structure:

Field	Type	Description
uuid	string	Unique identifier for the payment transaction
expires_at	string	Expiration timestamp
payment_link_url	string	URL of the payment link
payin_method_code	string	Code of the selected payment method
amount	number	Original payment amount
email	string	Customer's email address
description	string	Description of the payment transaction
webhook_notification	object	Webhook configuration details
└─ endpoint_url	string	URL where webhooks will be sent
└─ authorization_header	string	Authorization header for webhook
meta_data	object	Optional custom metadata to attach to the transaction
transaction_info	object	Information about the transaction
└─ uuid	string	UUID of transaction
└─ name	string	Name of sender
└─ currency	string	Currency code for the transaction
└─ total	number	Total payment amount
└─ paid_amount	number	Amount that has been paid
└─ status	string	The current status of the payment

Example:

{
  "uuid": "7AMCEF7H",
  "expires_at": "2025-10-02T19:05:03.971Z",
  "payment_link_url": "https://paymentgatewayv3.rc.cleverhub.co/N0FNQ0VGN0g",
  "payin_method_code": "my_ewallet_touchngo_myr",
  "amount": 3000,
  "email": "test@example.com",
  "description": "Test payin",
  "webhook_notification": {
    "endpoint_url": "https://webhook.site/12da7803-c4cf-4f32-812d-aaeaecf20d9d",
    "authorization_header": "****"
  },
  "meta_data": {
    "external_id": "1HUJMW34"
  },
  "transaction_info": {
    "uuid": "3D8G9WJJ",
    "name": "Ma Feng",
    "currency": "MYR",
    "total": 3000,
    "paid_amount": 3000,
    "status": "pending"
  }
}

Setting Up Webhooks

You can do this by including the webhook_notification object in your payment link creation request:

{
  "webhook_notification": {
    "endpoint_url": "https://your-domain.com/webhook",
    "authorization_header": "Bearer your-secret-token"
  }
}

Webhook Security

For enhanced security, you can include an authorization_header in your webhook configuration. This header will be sent with each webhook request, allowing you to verify the authenticity of the notifications.

Status Changes

Webhook notifications are sent when a payment's status changes to any of the following:

• pending: Customer started a new payment but hasn't proceeded yet.
• authorised: Payment has been authorised, ready to be captured.
• waiting: Payment has been approved, awaiting funds to settle.
• received: Funds have been received and are ready to be settled.
• expired: Payment session expired before completion.
• return_pending: Refund request initiated, awaiting processing.
• return_expired: The refund request has expired. Expiration time is set to be 10 days.
• partially_refunded: Partial refund has been issued to the customer.
• return_received: Full amount has been refunded to the customer.
• return_rejected: Refund request was denied. The system will not retry again.
• failed: Payment failed due to an error or decline.
• in_dispute: Customer has raised a dispute, under review.
• dispute_lost: Dispute has been resolved in customer's favour The disputed amount is not returned to the merchant.

Best Practices

1. Always verify the webhook signature or authorization header to ensure the request is legitimate
2. Implement idempotency in your webhook handler to prevent duplicate processing
3. Respond with a 200 OK status code as soon as you receive the webhook
4. Process the webhook data asynchronously to avoid timeout issues
5. Keep your webhook endpoint URL secure and private

Testing Webhooks

You can test webhook notifications using tools like webhook.site or by setting up a local endpoint using tools like ngrok.

Error Handling

If the target endpoint does not return HTTP 200, Hello Clever will retry the webhook call 3 times with 15 minutes delay per call.