Ko-fi

Ko-fi is a fully supported payment provider in PayGlue. When a supporter sends a tip, starts a membership, or buys from your Ko-fi Shop, PayGlue automatically creates or updates the matching Ghost member — no manual webhook registration required.

Warning: Ko-fi's webhook API only tells PayGlue when a membership starts — it never sends an event when a membership ends or is cancelled. If a supporter cancels their Ko-fi membership, you have to revoke their Ghost access manually. Ko-fi has stated it plans to expand its webhook events in the future.

Prerequisites

A Ko-fi account at ko-fi.com
A Ghost blog connected in PayGlue (Connect Ghost)

Steps

1. Open Ko-fi's Webhooks settings

In your Ko-fi account, go to Settings → Webhooks (under the API section).

[Screenshot — Ko-fi Settings → Webhooks page]

2. Copy the Webhook URL from PayGlue

In your PayGlue dashboard, go to Providers and click Connect Ko-fi. Copy the Webhook URL shown there.

Ko-fi connection page in PayGlue with the Webhook URL, Copy button and Verification Token field, webhook key blacked out

3. Paste the Webhook URL into Ko-fi

Paste the URL into Ko-fi's Webhook URL field and save.

[Screenshot — Ko-fi Webhooks settings with the PayGlue webhook URL pasted in]

4. Copy the Verification Token

Ko-fi shows a Verification Token on the same page. Copy it into the Verification Token field on the PayGlue Ko-fi connection page, then click Save credentials.

Note: The verification token is the only credential Ko-fi requires. Ko-fi has no API for PayGlue to call directly — the token is only ever checked passively, when Ko-fi sends a webhook.

5. Run a health check

Click Run health check to confirm the verification token is saved. Because Ko-fi has no API endpoint to call, this only confirms PayGlue is configured — it does not confirm delivery. Trigger a test webhook from Ko-fi's dashboard to confirm end-to-end delivery.

6. Create a mapping

Ko-fi has no API to fetch your tiers or shop items, so Buy Button, Paywall, and Pricing Table all use a manual text field instead of a product dropdown:

For a membership tier, type the exact tier name as it appears on your Ko-fi page (e.g. Gold Tier).
For a Shop item, paste the item's share link (Share → Copy link on Ko-fi, e.g. https://ko-fi.com/s/c0e30e5fcf) — PayGlue extracts the product code automatically and fills the checkout/button URL for you. Ko-fi's webhook never includes the item's name, only this code, so the share link is the only reliable way to identify a specific Shop item.
For plain tips, use kofi-support.

Choose which Ghost newsletter to subscribe the supporter to and which welcome email to send, then save.

From this point on, every Ko-fi tip, membership payment, or shop order triggers automatic Ghost member creation.

7. Test your setup

Use Ko-fi's Send Test button on the Webhooks settings page, or make a real test payment. Then open Analytics → Webhook Events in your PayGlue dashboard — the event should appear with status Processed and the supporter's email should appear as a new member in Ghost Admin.

Supported events

Ko-fi's API is webhook-only and event-driven — it has no endpoints to fetch products, shop contents, or a supporter's current membership status. Every payment type Ko-fi sends a webhook for represents money actually received, so PayGlue maps all of them to a single "purchase completed" action:

Ko-fi event type	PayGlue action
`Tip` (also sent as `Donation` by Ko-fi's own "Send Test" button)	Create Ghost member
`Subscription` (membership payment)	Create or confirm active Ghost member
`Shop Order`	Create Ghost member
`Commission`	Create Ghost member

There is no Ko-fi event for a cancelled or ended membership — see the warning above.

Note: A Shop Order webhook never includes the purchased item's name — only an opaque direct_link_code per item (the code at the end of that item's Ko-fi share link). This is why Shop item mappings are keyed on that code rather than a product title; see the mapping step above. A single order can contain several items, and PayGlue grants an entitlement for each one independently.

Troubleshooting

Connection stays "Not connected" after saving

A Ko-fi connection requires only a Verification Token. If the status still shows "Not connected — a verification token is required" after saving, re-copy the token from Ko-fi's Webhooks settings page and save again — trailing spaces or a partial copy are the most common cause.

Health check passes but no events arrive

The health check only confirms the token is saved, not that Ko-fi is delivering webhooks. Use Ko-fi's Send Test button on its Webhooks settings page, then check Analytics → Webhook Events in PayGlue.

Test webhook from Ko-fi's dashboard is not processed

Ko-fi's "Send Test" button sends the legacy type Donation instead of the current Tip. PayGlue accepts both — if a test event still fails, check Analytics → Webhook Events for the actual error rather than assuming the type is unsupported.

Ghost member is not created after a payment

Open the event in Analytics → Webhook Events and check the error message. The most common cause is a missing mapping — PayGlue receives the event but takes no action unless there is an active mapping for that Ko-fi product.

A cancelled Ko-fi member still has Ghost access

This is expected, not a bug. Ko-fi never sends a membership-ended webhook, so PayGlue cannot detect cancellations automatically. Revoke the Ghost member's access manually in Ghost Admin.

Webhook signature verification

Ko-fi does not sign its webhook payloads with a cryptographic signature. Instead, every payload includes the Verification Token you configured in Ko-fi's dashboard, and PayGlue checks it against the token stored for your account before processing the event. Keep this token private — anyone who has it can send PayGlue fake Ko-fi events for your tenant.