Setting up Webhooks

Introduction

Donation Store allows you to setup webhooks which are executed whenever a particular event occurs on your webstore. They are a great way to extend the functionality of Donation Store and customise it. A webhook will make a request to a particular URL with JSON data that you choose. This request should be handled by a script of your choice. The beauty of this is that you can host your webhooks separately, away from Donation Store and write them in a completely different language. So far there are two types of webhooks:

• Payment Webhooks
• User Verification Webhooks

The following goes into detail on how to set them up and what is expected for using them. All Donation Store plans come with the ability to use webhooks.

Setting up Webhooks

To setup a payment webhook, go to the "Webhooks" section of the Donation Store control panel (on the webstore of your choice). This can be found in the left hand navigation bar in the control panel. Once there click "Create Webhook".

You must provide the following information to create a webhook:

• URL: The URL that Donation Store will send a request to when the particular event happens.
• Secret: The secret key (made by you) that is used to sign the request for security.
• Execute When: When the webhook is to be executed.

Currently there are two types of webhooks, but there are plans to add more as people request them.

Payment Webhooks

Payment webhooks get executed once a payment has been made. They are only made after the customer's selected payment gateway responds that the payment was made successfully. A payment webhook could be used to perhaps add forum titles, Discord roles, trigger in-game events or even for recording your own statistics.

To make sure all requests received by you are legitimate, we recommend that you check the signature sent. The signature sent is calculated using a sha256 of the secret, the transaction id, the UUID of the user who purchased the item and their email. This should be concatenated with the secret and then hashed. To check, the string would be generated using the following (implemented in Python):

hashlib.sha256(secret_key + request.body['transaction_id'] + request.body['uuid'] + request.body['email']).hexdigest()

The signature is sent in the HTTP_AUTHORIZATION header.

When sent, Donation Store expects a code 200 response from your script when it receives the below payload. If it does not receive this code, it will try up to 5 times until the webhook is recorded as failed. Donation Store will send this data using a HTTP POST request.

Example Payload

{
	"webhook_type": "payment",
	"payment": {
		"transaction_id": "123",
		"date": "2018-06-15 12:12:12",
		"amount": 50,
		"currency": "EUR",
		"gateway": "Xsolla",
		"status": "Complete"
	},
	"customer": {
		"username": "MCxJB",
		"uuid": "5b05c7cc311841c78993ef9f3ba5fb63",
		"email": "[email protected]",
		"ip": "123.456.789",
		"name": "Mark Barrett",
		"address": "123 Fake Street"
	},
	"packages": [{
		"id": 123,
		"name": "Sword",
		"quantity": 2,
		"server_to_execute": null,
		"price": 2.00,
		"sub_total": 4.00,
		"customer_choose_price": null,
		"variables": [{
			"identifier": "type",
			"choice": "minecraft:diamond_sword"
		}]
	}],
	"coupons": [{
		"code": "20OFF",
		"discount_type": "percentage",
		"discount_percentage": "20",
		"discount_amount": "0"
	}],
	"gift_cards": [{
		"code": 12345,
		"amount": 0.10
	}],
	"virtual_currencies": [{
		"code": "MST",
		"amount_used": 1.00
	}]
}

User Verification Webhooks

The user verification webhook is used to validate a user logging into your webstore. It will only check to see if a user is verified on that particular store, so if you have more than one store, they each need that webhook set.

The rules for verification are entirely up to you and can range from checking if the user is banned on a list, checking if they have logged into a server before, or even checking to see if they have an account on your forum etc.

The webhook will send a HTTP request to your webhook where you can do any checks that you desire. If the user is verified you return a success message (example below), if not you send an unsuccessful message with a message set of your choice that will be displayed on your webstore as an error message.

Donation Store does requires a sha256 like the Payment Webhook but concatenates the webhook secret, the user's uuid and their IP address. An example of this in Python would be:

hashlib.sha256(secret_key + request.body['user']['uuid'] + request.body['user']['ip']).hexdigest()

Example Payload

{
    "webhook_type": "user_verification",
    "user": {
        "ign": "MCxJB",
        "uuid": "5b05c7cc311841c78993ef9f3ba5fb63",
        "ip": "123.456.789",
    }
}

Donation Store then expects one of the following responses (in both cases whether they are verified or not, you must return a HTTP 200)

Successful Response

{
    "verified": true,
}

Unsuccessful Response

{
    "verified": false,
    "message": "Some error message to be displayed above the login."
}

If you need help with these web hooks please open a support ticket and we will be glad to help!