Webhooks for Payment Links
Webhooks let you receive real-time HTTP POST notifications when a Payment Link's status changes. Instead of polling the API for updates, you configure a webhook URL and Nimbbl sends event data to your server automatically.
Setting Up Webhooks
Configure your webhook URL through the following method:
- Support team -- contact [email protected] to have the Nimbbl team configure webhook URLs for your account
Webhooks are sent as HTTP POST requests with a JSON payload containing payment link details, status information, and any custom attributes you attached to the link.
Supported Webhook Events
Payment Links support seven webhook events that cover the complete lifecycle of a link. Each event fires when the corresponding status transition occurs.
| Event Name | Trigger |
|---|---|
payment_link_created | A Payment Link has been created |
payment_link_sent | The link notification has been dispatched via SMS or email |
payment_link_opened | The customer has opened the Payment Link |
payment_link_authorized | The customer has completed payment and funds are authorized but not yet captured (pre-auth orders only) |
payment_link_paid | Full payment against the link has been completed |
payment_link_cancelled | The Payment Link has been explicitly cancelled |
payment_link_expired | The Payment Link has passed its expiration date |
There is no payment_link_scheduled or payment_link_partially_paid event today — Payment Links don't currently support partial payment.
Pre-Authorization Payment Links
When a Payment Link is configured with capture_mode=manual, the customer completes the payment flow and funds are authorized but not immediately settled. In this case:
- A
payment_link_authorizedevent fires first — the link moves toauthorizedstatus and a new authorization transaction is created. The underlying order moves tolapsedwithlapsed_reasonpayment_authorized. - The payment link remains in
authorizedstatus until you call the Capture API or Void API - Once captured, a
payment_link_paidevent fires and the link moves topaidstatus - If voided, the link moves to
cancelledstatus and the underlying order remainslapsed
The payment_link_authorized payload includes the transaction's authorization_details.authorized_time and authorization_details.expiry_time fields so you know how long the authorization hold is valid.
Webhook Payload
Each webhook event delivers a JSON payload that includes:
- Payment Link ID and Invoice ID
- Current status and previous status
- Payment amount and currency
- Customer details
- Transaction details (for payment events)
- Custom attributes and tags
Webhooks support both encrypted and unencrypted payloads depending on your configuration. For detailed payload structure, see Payment Link Webhooks; for encryption options and delivery best practices, see Webhook Payloads.
Best Practices
- Respond quickly -- return a 2xx HTTP status code within a few seconds to acknowledge receipt. Process the webhook data asynchronously if needed.
- Handle duplicates -- design your webhook handler to be idempotent. The same event may be delivered more than once.
- Verify the payload -- validate webhook signatures to confirm the request originated from Nimbbl.