My idea starts from here:
Ko-Fi is a donation platform. They have an API that can send HTTP POST requests to a webhook.
https://ko-fi.com/manage/webhooks (the page needs to be logged in though it’s just documentation, so I’ll copy-paste:
Ko-Fi Webhooks documentation
Webhook URL
We will send an HTTP POST to your specified URL when a payment completes. Your URL must start with https://
Verification Token
The verification token below will be included with every request to your webhook. It is a lightweight approach to increasing your confidence that Ko-fi servers are the source of requests to your webhook. Ensure that this level of confidence is suitable for your application. For example, note that the verification token is sent as plain text.
XXXXXXXXXXXXXXXXXXXXX
Receiving and Responding
The data is sent (posted) with a content type of application/x-www-form-urlencoded
. A field named ‘data’ contains the payment infomation as a JSON string.
Your listener should return a status code of 200
. If we don’t receive this status code, we’ll retry a reasonable number of times with the same message_id.
The type
field will be Donation
, Subscription
, Commission
, or Shop Order
.
Monthly subscription payments will have is_subscription_payment
set to true
.
The first time someone subscribes, is_first_subscription_payment
will be true
.
If the subscription is for a membership tier, then tier_name
will contain the name you have assigned to the tier.
For a shop order, shop_items
will contain an array of shop item objects each with a single property, the direct_link_code
.
Important: If you are using Webhooks to show payments publicly, you must respect the is_public
field, and hide the message if the value is false
If you don’t have a server set up to receive webhooks but want to test the examples below, we suggest using a service like https://webhook.site/
to inspect the requests we send.
Example: Single Donation
Here’s an example of the data that will be sent for a single donation:
data = {
"verification_token": "d8546b84-c698-4df5-9812-39d35813e2ff",
"message_id": "78b207f2-9e6c-4ea7-b47f-5454709824aa",
"timestamp": "2023-02-13T22:39:12Z",
"type": "Donation",
"is_public": true,
"from_name": "Jo Example",
"message": "Good luck with the integration!",
"amount": "3.00",
"url": "https://ko-fi.com/Home/CoffeeShop?txid=00000000-1111-2222-3333-444444444444",
"email": "jo.example@example.com",
"currency": "USD",
"is_subscription_payment": false,
"is_first_subscription_payment": false,
"kofi_transaction_id": "00000000-1111-2222-3333-444444444444",
"shop_items": null,
"tier_name": null,
"shipping": null
}
(etc)
I would like to add a donation progress bar on my Discourse forum, which would be updated when Discourse receives such a request.
Can a theme component receive these requests, or would it need a plugin?
Where should I start if this is possible with a theme component (or a plugin if needed)? Just a few clues or pointers would be great