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 one of two methods:
- Command Center -- navigate to Developer Settings and configure your webhook endpoint under the Webhooks section
- 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 eight 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_scheduled | A notification for the link is queued for future delivery |
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_paid | Full payment against the link has been completed |
payment_link_partially_paid | A partial payment has been made against the link |
payment_link_cancelled | The Payment Link has been explicitly cancelled |
payment_link_expired | The Payment Link has passed its expiration date |
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, encryption options, and best practices for handling webhooks, see the Webhooks guide.
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.