Adapters
Send Yolfi webhook events in provider-compatible formats
Overview
Webhook adapters help merchants reuse existing payment webhook handlers when adding Yolfi. Instead of receiving the native Yolfi webhook body, your endpoint can receive a Stripe-compatible or Lemon Squeezy-compatible JSON payload.
Adapters convert field names and event names. They do not change webhook authentication: every adapted webhook is still signed by Yolfi and should be verified with X-Yolfi-Signature.
Minimal-change contract: keep the same webhook URL and business handlers; only add Yolfi signature verification/routing and adapter payload handling.
Adapters work best with webhook handlers that process the event body directly. If your existing handler fetches provider objects through the provider API, keep that branch unchanged and use a separate Yolfi endpoint or an existing body-driven handler.
Install adapter mode with an AI assistant
Use the Yolfi webhook integration skill when you want an assistant to reuse an existing Stripe or Lemon Squeezy webhook flow safely.
Supported Adapters
| Adapter | Best for |
|---|---|
| Stripe | Existing handlers for Checkout, PaymentIntent, Charge, Invoice, or Subscription events |
| Lemon Squeezy | Existing handlers for order and subscription lifecycle events |
How It Works
Yolfi emits a small set of payment lifecycle events. Some providers emit several webhook events for the same lifecycle moment, so an adapter can send multiple provider-compatible payloads for one Yolfi event.
For example, one Yolfi payment.confirmed event with the Stripe adapter can send:
payment_intent.succeededcharge.succeededcheckout.session.completed
Your endpoint receives each payload as a separate POST request.
Use X-Yolfi-Event-ID as the source lifecycle identifier. One source event can intentionally fan out into multiple adapter payloads.
Security
Check Webhook Signatures for verification information.
Field Mapping
Adapters put values into provider-native fields whenever there is a direct match. Provider-specific metadata is used only for Yolfi or blockchain fields that the provider does not have a native field for, such as:
- Yolfi invoice, paylink, organization, and subscription IDs
- blockchain network and chain ID
- token contract address and symbol
- merchant metadata
Adapter payloads are compatibility payloads, not canonical provider-owned objects.
Setup
- Open organization settings in the Yolfi dashboard.
- Set your webhook URL.
- Select an adapter.
- Save changes.
What should not change:
- Your fulfillment/subscription business logic.
- Your provider webhook verification path for real provider requests.
- Your data model, provider enums, checkout URLs, or plan configuration.