Using Webhooks

Learn how you can offer more advanced awards when a user makes a purchase!

Getting Started

With Donate Bot webhooks, you can sell any product or service for your Discord bot, server, and more! It's super simple to start integrating.

Use Cases

  • Sell features for your Discord bot

  • Offer additional rewards for server roles

  • Sell features for your own website or application

Webhook

Webhooks are sent as POST requests.

Here is what our webhook will look like when you set a URL in Donate Bot Settings.

Request Headers

If you do not verify your authorization token, purchases could be spoofed.

Key

Description of Value

authorization

The token you set inside Donate Bot Settings. Should be kept completely secret and never revealed outside of your server.

Request Body (JSON)

Key

Type

Description of Value

txn_id

String

The transaction ID from the PayPal payment (We recommend storing this to keep track of payments). This ID also matches to each purchase on the PayPal dashboard.

status

String

PayPal status of the transaction. See the table below for more details.

recurring

Boolean

If the purchase is a recurring payment. (Only set on status: completed, reversed, or refunded)

buyer_email

String

The email address of the buyer (provided by PayPal)

price

String

Price of the purchase (Ex: 4.99)

currency

String

Currency code of the purchase (Ex: USD)

buyer_id

String

Buyer/Discord ID of the purchaser (If no buyer is selected, the field will be empty)

role_id

String

Role ID of the purchase (If the purchase was not a role, this field will be empty)

product_id

String

Product ID of the purchase (If the purchase was a role, this field will be empty)

guild_id

String

Guild/Server ID of the purchase

Statuses

Status Value

Type

Description

completed

All Payments

When a transaction has been completed and funds are now in your account.

reversed

All Payments

When a transaction charge-back occurs from the buyer.

refunded

All Payments

When the seller decides to refund the purchase.

sub_ended

Subscriptions Only

When a subscription has ended.

Transaction Flow

Expect each webhook to be sent multiple times with a different status. When a payment is completed, reversed, refunded, or if a subscription is canceled.

Success/Completion Flow

As you can see, when a purchase first occurs, your webhook data is sent as well as status: "completed". After the purchase, you can expect the same webhook to be sent except with a different status value. View the chart below for more details.

Reverse/Refund/Subscription Ended Flow

Recurring Payments

A recurring payment acts just like a standard one. You will receive the webhook with status: "completed" in the request body. Determine if a payment is recurring by the recurring Boolean in the request body. When a subscription is canceled or the payment method expires, another webhook will be sent with status: "sub_ended".

Testing

In order to properly test your application and ensure webhooks work, testing is built in to the Donate Bot Control Panel. Just visit the webhook options under the Settings page of Donate Bot.

We recommend using a free service like Request Catcher to test our webhooks.

Here is what data from a Test Completion looks like:

{
"txn_id": "32972532BD432764B",
"buyer_email": "[email protected]",
"price": "4.99",
"currency": "USD",
"buyer_id": "349714792719843329",
"role_id": "479793572267425842",
"guild_id": "404394509917487105",
"recurring": false,
"status": "completed"
}

Here is what data from a Test Reversal looks like:

{
"txn_id": "32972532BD432764B",
"buyer_email": "[email protected]",
"price": "4.99",
"currency": "USD",
"buyer_id": "349714792719843329",
"role_id": "479793572267425842",
"guild_id": "404394509917487105",
"recurring": false,
"status": "reversed"
}

Examples

Node.JS using Express

app.js
var express = require('express');
var app = express();
var bodyParser = require('body-parser');
app.use(bodyParser.json());
app.post('/webhooks', function(request, response) {
// Send OK so server knows we got the webhook
response.sendStatus(200);
// Use a different token in actual use
var authenticationToken = "mytoken";
// Verify the token set here and the one from the webhook server match
if (request.headers.authorization === authenticationToken) {
var webhook = request.body;
// webhook contains the webhook's body
}
});
app.listen(8080, function() {
console.log("Listening on port 8080");
});