Webhooks
Learn how to receive real-time payment notifications via webhooks
Overview
Webhooks enable your application to receive real-time notifications whenever payment events occur in your account. Instead of polling our API for payment status, webhooks push events directly to your server the moment something happens.
Webhooks are the most reliable way to track payment events. Use them to automatically update your system, trigger fulfillment, or send confirmation emails.
Add webhooks with an AI assistant
Use the Yolfi webhook integration skill to help an AI coding assistant wire this into your backend safely.
How Webhooks Work
When a payment-related event occurs in our system, we send an HTTP POST request to your configured webhook URL. Your server should respond with a 200 OK status to acknowledge receipt.
Event Types
Invoice Events
| Event | Description |
|---|---|
invoice.created | Payment initiated, invoice created |
invoice.overdue | Invoice payment deadline passed without payment |
Payment Events
| Event | Description |
|---|---|
payment.confirmed | Payment confirmed with enough confirmations and amount |
Subscription Events
| Event | Description |
|---|---|
subscription.overdue | Subscription renewal deadline passed without payment |
subscription.cancelled | Subscription was cancelled |
Use payment.confirmed as your primary fulfillment trigger. This ensures payment is fully confirmed before you deliver service.
Quick Setup
Set your webhook URL in your organization settings via the API or dashboard.
Use your API key to verify incoming webhook requests are authentic.
Process the webhook payload and respond with 200 OK quickly.
Retry Policy
If your server returns a non-2xx status code or times out, we will retry the webhook:
- Immediate retry - First attempt after failure
- Second attempt - 2 minutes after first retry
- Final attempt - 2 minutes after second retry
Duplicate deliveries are expected during retries. Your handler should be idempotent and deduplicate by X-Yolfi-Event-ID.
After 3 failed attempts, the webhook is marked as failed. Ensure your endpoint is reliable and returns 200 OK quickly.
Deadlines
| Scenario | Deadline |
|---|---|
| First payment (one-time or recurring) | 1 hour |
| Recurring cycles (after first payment) | 24 hours |
After an invoice deadline, invoice.overdue is sent for that invoice. For recurring subscriptions, do not treat invoice.overdue as a subscription cancellation by itself; use subscription.overdue or subscription.cancelled for subscription access changes.
Consistent Event Model
All webhook events follow the same structure and include:
- Identifier -
id,invoiceId,orgId - Amount -
amount(final merchant receivable, formatted),amountUsd(USD equivalent) - Pricing context -
currency(source currency),rate(payment-token quote) - Type -
paymentType(ONE_TIMEorRECURRING) - Status - Current state of the invoice/payment
- Customer - Customer info for fulfilling orders