About webhook payloads for a GitHub Marketplace listing

A Marketplace purchase event triggers when a user purchases, cancels, or changes their payment plan. For details on how to respond to each of these types of events see Administering listing plans and user accounts.

Marketplace purchase webhook payload

Webhooks POST requests have special headers. See "Webhook delivery headers" for more details. Each marketplace_purchase webhook payload will have the following information:

Key Type Description
action string The action performed to generate the webhook. Can be purchased, cancelled, or changed.
effective_date string The date the action becomes effective.
sender object The person that took the action that triggered the webhook.
marketplace_purchase object The GitHub Marketplace purchase information.

The marketplace_purchase object has the following keys:

Key Type Description
account object The organization or user account associated with the subscription.
billing_cycle string Can be yearly or monthly. When the account owner has a free GitHub plan and has purchased a free GitHub Marketplace plan, billing_cycle will be nil.
unit_count integer Number of units purchased.
on_free_trial boolean true when the account is on a free trial.
free_trial_ends_on string The date the free trial will expire.
next_billing_date string The date that the next billing cycle will start. When the account owner has a free GitHub.com plan and has purchased a free GitHub Marketplace plan, next_billing_date will be nil.
plan object The plan purchased by the user or organization.

The plan object has the following keys:

Key Type Description
id integer The unique identifier for this plan.
name string The plan's name.
description string This plan's description.
monthly_price_in_cents integer The monthly price of this plan in cents (US currency). For example, a listing that costs 10 US dollars per month will be 1000 cents.
yearly_price_in_cents integer The yearly price of this plan in cents (US currency). For example, a listing that costs 100 US dollars per month will be 10000 cents.
price_model string The pricing model for this listing. Can be one of flat-rate, per-unit, or free.
has_free_trial boolean true when this listing offers a free trial.
unit_name string The name of the unit. If the pricing model is not per-unit this will be nil.
bullet array of strings The names of the bullets set in the pricing plan.


Example webhook payload for a purchased event

{
   "action":"purchased",
   "effective_date":"2017-10-25T00:00:00+00:00",
   "sender":{
      "login":"username",
      "id":3877742,
      "avatar_url":"https://avatars2.githubusercontent.com/u/3877742?v=4",
      "gravatar_id":"",
      "url":"https://api.github.com/users/username",
      "html_url":"https://github.com/username",
      "followers_url":"https://api.github.com/users/username/followers",
      "following_url":"https://api.github.com/users/username/following{/other_user}",
      "gists_url":"https://api.github.com/users/username/gists{/gist_id}",
      "starred_url":"https://api.github.com/users/username/starred{/owner}{/repo}",
      "subscriptions_url":"https://api.github.com/users/username/subscriptions",
      "organizations_url":"https://api.github.com/users/username/orgs",
      "repos_url":"https://api.github.com/users/username/repos",
      "events_url":"https://api.github.com/users/username/events{/privacy}",
      "received_events_url":"https://api.github.com/users/username/received_events",
      "type":"User",
      "site_admin":true,
      "email":"username@email.com"
   },
   "marketplace_purchase":{
      "account":{
         "type":"Organization",
         "id":18404719,
         "login":"username",
         "organization_billing_email":"username@email.com"
      },
      "billing_cycle":"monthly",
      "unit_count":1,
      "on_free_trial":false,
      "free_trial_ends_on":null,
      "next_billing_date":"2017-11-05T00:00:00+00:00",
      "plan":{
         "id":435,
         "name":"Basic Plan",
         "description":"Basic Plan",
         "monthly_price_in_cents":1000,
         "yearly_price_in_cents":10000,
         "price_model":"per-unit",
         "has_free_trial":true,
         "unit_name":"seat",
         "bullets":[
            "Is Basic",
            "Because Basic "
         ]
      }
   }
}

Example webhook payload for a changed event

Changing the plan includes upgrading or downgrading.

{
   "action":"changed",
   "effective_date":"2017-10-25T00:00:00+00:00",
   "sender":{
      "login":"username",
      "id":3877742,
      "avatar_url":"https://avatars2.githubusercontent.com/u/3877742?v=4",
      "gravatar_id":"",
      "url":"https://api.github.com/users/username",
      "html_url":"https://github.com/username",
      "followers_url":"https://api.github.com/users/username/followers",
      "following_url":"https://api.github.com/users/username/following{/other_user}",
      "gists_url":"https://api.github.com/users/username/gists{/gist_id}",
      "starred_url":"https://api.github.com/users/username/starred{/owner}{/repo}",
      "subscriptions_url":"https://api.github.com/users/username/subscriptions",
      "organizations_url":"https://api.github.com/users/username/orgs",
      "repos_url":"https://api.github.com/users/username/repos",
      "events_url":"https://api.github.com/users/username/events{/privacy}",
      "received_events_url":"https://api.github.com/users/username/received_events",
      "type":"User",
      "site_admin":true,
      "email":"username@email.com"
   },
   "marketplace_purchase":{
      "account":{
         "type":"Organization",
         "id":18404719,
         "login":"username",
         "organization_billing_email":"username@email.com"
      },
      "billing_cycle":"monthly",
      "unit_count":10,
      "on_free_trial":false,
      "free_trial_ends_on":null,
      "next_billing_date":"2017-11-05T00:00:00+00:00",
      "plan":{
         "id":435,
         "name":"Basic Plan",
         "description":"Basic Plan",
         "monthly_price_in_cents":1000,
         "yearly_price_in_cents":10000,
         "price_model":"per-unit",
         "has_free_trial":true,
         "unit_name":"seat",
         "bullets":[
            "Is Basic",
            "Because Basic "
         ]
      }
   },
   "previous_marketplace_purchase":{
      "account":{
         "type":"Organization",
         "id":18404719,
         "login":"username",
         "organization_billing_email":"username@email.com"
      },
      "billing_cycle":"monthly",
      "on_free_trial":false,
      "free_trial_ends_on":null,
      "unit_count":1,
      "plan":{
         "id":435,
         "name":"Basic Plan",
         "description":"Basic Plan",
         "monthly_price_in_cents":1000,
         "yearly_price_in_cents":10000,
         "price_model":"per-unit",
         "has_free_trial":true,
         "unit_name":"seat",
         "bullets":[
            "Is Basic",
            "Because Basic "
         ]
      }
   }
}

Example webhook payload for a cancelled event

{
   "action":"cancelled",
   "effective_date":"2017-10-25T00:00:00+00:00",
   "sender":{
      "login":"username",
      "id":3877742,
      "avatar_url":"https://avatars2.githubusercontent.com/u/3877742?v=4",
      "gravatar_id":"",
      "url":"https://api.github.com/users/username",
      "html_url":"https://github.com/username",
      "followers_url":"https://api.github.com/users/username/followers",
      "following_url":"https://api.github.com/users/username/following{/other_user}",
      "gists_url":"https://api.github.com/users/username/gists{/gist_id}",
      "starred_url":"https://api.github.com/users/username/starred{/owner}{/repo}",
      "subscriptions_url":"https://api.github.com/users/username/subscriptions",
      "organizations_url":"https://api.github.com/users/username/orgs",
      "repos_url":"https://api.github.com/users/username/repos",
      "events_url":"https://api.github.com/users/username/events{/privacy}",
      "received_events_url":"https://api.github.com/users/username/received_events",
      "type":"User",
      "site_admin":true,
      "email":"username@email.com"
   },
   "marketplace_purchase":{
      "account":{
         "type":"Organization",
         "id":28536653,
         "login":"organizationUsername",
         "organization_billing_email":"organizationusername@gmail.com"
      },
      "billing_cycle":"monthly",
      "unit_count":0,
      "on_free_trial":false,
      "free_trial_ends_on":null,
      "next_billing_date":"2017-11-08T00:00:00+00:00",
      "plan":{
         "id":686,
         "name":"Premium Plan",
         "description":"Premium Plan",
         "monthly_price_in_cents":10000,
         "yearly_price_in_cents":100000,
         "price_model":"flat-rate",
         "has_free_trial":true,
         "unit_name":null,
         "bullets":[
            "Is Expensive",
            "And Flat Rate"
         ]
      }
   }
}