Yolfi Documentation

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.

Open AI Integrations

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 the endpoint-specific signing secret returned when the webhook is created or rotated. Never use the organization API key for signature verification.

Process the webhook payload and respond with 200 OK quickly.

API key and signing secret

The organization API key authorizes webhook management calls. It does not sign deliveries. Creating an endpoint returns a separate endpoint-specific signing secret:

curl -X POST https://app.yolfi.com/api/private/organization/webhook-endpoints \
  -H "Authorization: Bearer $YOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://merchant.example/webhooks/yolfi",
    "adapter": "NONE",
    "enabled": true
  }'

{
  "success": true,
  "data": {
    "id": "WEBHOOK_ENDPOINT_ID",
    "signingSecret": "ENDPOINT_SIGNING_SECRET"
  }
}

Store signingSecret when it is returned. Endpoint list and update responses do not expose it. If it is lost, rotate it with POST /api/private/organization/webhook-endpoints/WEBHOOK_ENDPOINT_ID/rotate-secret and update the receiving service.

Test Webhooks

Use Settings -> Webhooks in the dashboard to send a test webhook event to your configured endpoint. Test events use the same delivery path, webhook adapter, and X-Yolfi-Signature header as live events, but their payload contains livemode: false and an evt_test_ event ID.

Test webhooks do not create invoices, payment events, sweeps, subscriptions, or customer records. They only validate endpoint delivery and payload handling.

Retry Policy

If a delivery fails, we retry with exponential backoff - up to 5 attempts per event:

Attempt	When
1	Immediately
2	~10 seconds later
3	~30 seconds later
4	~90 seconds later
5	~270 seconds later

We retry on 5xx responses, 429 Too Many Requests, and connection or timeout errors. After 5 consecutive failures the event is marked failed and enters a 1-hour cooldown, after which delivery is retried again.

Other 4xx responses (for example 400, 401, 403, 404) are treated as permanent failures and are not retried - fix your endpoint or signature verification and send a new event.

Duplicate deliveries are expected during retries. Your handler should be idempotent and deduplicate by the signed payload id. You may also require X-Yolfi-Event-ID to equal that payload value.

Return 200 OK quickly. Slow responses can time out and count as a failed attempt.

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_TIME or RECURRING)
Status - Current state of the invoice/payment
Customer - Customer info for fulfilling orders

Webhooks