Webhook Integration Guide

Use webhooks to be notified about events that happen on your Digital Goods Store account, such as orders and subscription payments. If you need help after reading this, please contact us via our support page and we will be able to assist.

What is a webhook?

A webhook allows you to register a URL that we will be notified anytime an event happens in your account. When an event occurs, for example, when an order is placed, Digital Goods Store creates an Event object. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Stripe then sends the Event object to any URLs in your account's webhooks settings via an HTTP POST request.

You might use webhooks to:

Configuring your webhook settings

Webhooks are configured in the webhooks settings section of your Selling Preferences.

You can enter any URL you'd like to have receive the events, but this should be a dedicated page on your server, coded per the instructions below.

Receiving a webhook notification

Creating a webhoook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON.

Example PHP:

// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event_json = json_decode($input);

// Do something with $event_json

http_response_code(200); // PHP 5.4 or greater

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3xx codes, will indicate to Digital Goods Store that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure.

When a webhook is not successfully received for any reason, Digital Goods Store will continue trying to send the webhook once an hour for up to 5 more times.

Webhook JSON data

The JSON data that is sent in the POST request body contains the following example data:

{
    "id":"dgs_zwnpayvr",
    "created":"2015-11-19T12:36:59+00:00",
    "type":"order.placed",
    "order":{
        "date":"2015-11-19 12:36:57",
        "order_id":"G12WPYVZDM",
        "payment_status":"Completed",
        "currency_code":"USD",
        "amount_total":"23.00",
        "amount_tax":"0.00",
        "buyers_email":"support@digitalgoodsstore.com",
        "buyers_first_name":"John",
        "buyers_last_name":"Doe",
        "buyers_country_code":"GB",
        "buyers_ip_address":"217.45.101.173",
        "description":"My First eBook",
        "active":true,
    	"subscription":false,
        "products":[
            {
                "code":null,
                "name":"My First eBook",
                "quantity":"1",
                "price":"23.00"
            }
        ]
    },
    "invoice":{
        "date":"2015-11-20 12:36:57",
        "payment_status":"Completed",
        "transaction_id":"1WX23894BX247612J",
        "amount_total":"23.00",
        "amount_tax":"0.00"
    }
}

Attributes:

id string (12) This is an identifier that is unique to each webhook call.

It is advised to check this against previous calls as not to process the same request twice.
date timestamp -
type string This defines the type of event is being sent.

Possible values:

order.placed When an order is initially made.
order.updated When an order is updated, such as 'payment_status'.
subscription.payment When a payment is made to a subscription order.
order array The order details.

Important attributes:

active boolean If active then customer has access to the downloads.
subscription boolean Whether the order is a subscription.
products array An array of products included in the order.

Important attributes:

code string Your unique product identifier.
name string The product title.
quantity integer The quantity of items purchased.
price float The total price of the quantity.
invoice array If the payment is part of a subscription order then the individual payment invoice is supplied, otherwise this will not be included.

Important attributes:

payment_status string The payment status of the individual payment.
transaction_id string The unique payment identifier for the invoice.

More Information

If you need help after reading this, please contact us via our support page and we will be able to assist.