Stripe Webhook

This integration will make sure that your customers purchases are tracked.

If you use Stripe to track customer purchases, you can set up a webhook integration so PartnerStack can listen for events relating to charges and subscriptions. Once we receive information about a customer paying for your product, we can record that payment in PartnerStack and ensure your partners are properly attributed!

Supported Stripe Events

PartnerStack supports listening for the following events from Stripe per their developer documentation:

  • customer.created, customer.updated: When this event is received, a customer is either created or updated on the platform. We sync Stripe's Customer ID to the customer record in PartnerStack, allowing us to record future transactions for this customer from Stripe!
  • charge.succeeded, charge.captured, charge.updated: When we receive any of these events, a transaction is recorded under the associated customer in PartnerStack
  • charge.refunded, charge.failed: When we receive these events, we delete the original transaction in PartnerStack, if it exists.

Alternatively, we can listen for invoice.payment_succeeded events instead of charge.succeeded events for recording transactions on the platform.


The transaction amount recorded in PartnerStack is different for the charge.succeeded event and the invoice.payment_succeeded event.
The amount is taken from the amount field on the charge.succeeded event where the amount is taken from the subtotal field on the invoice.payment_succeeded event. The amount cannot be customized.

Get your Webhook URL

In the PartnerStack dashboard. Navigate to Settings > Integrations > Webhooks and select Stripe from the Supported integrations.


Create the Webhook on the Stripe Dashboard

  1. Log into your Stripe dashboard.
  2. On the left sidebar, click "Developers", then "Webhooks".
  3. Click on "+ Add Endpoint" and fill in the URL you copied from your PartnerStack dashboard!
  4. Select the events you'd like to send to PartnerStack.
  5. Click "Add endpoint" and you're good to go!

Add customer key to Stripe Metadata

Whenever you interact with Stripe to record transactions under a customer, you need to let PartnerStack know which customer you're referring to. At PartnerStack, we identify customers using their customer key. This can be any value that uniquely identifies customers on your platform, for example their email address.

If you're using PartnerStackJS, this would be the value you used for when the customer signed up. If you used our PartnerStack API to create the customer record, this would be the value you passed as the key.

PartnerStack looks for customer_key in the Stripe metadata to identify customers. Below is an example of how this could work on your back-end, but your implementation may vary based on how your product interacts with Stripe!

ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with PartnerStackJS

# import stripe
# stripe.api_key = "sk_test_w82a3du.."
# stripe.Customer.create(
#     source="tok_18sjJiIDkGDhAX2xt24vr4Zx"
# )
ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

# require "stripe"
# Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
# Stripe::Customer.create(
    :metadata => {'customer_key' => <YOUR_CUSTOMERS_KEY>}
#   :description => "Customer for [email protected]",
#   :source => "tok_189fT12eZvKYlo2CYj4YoHKu" # obtained with Stripe.js
# )
ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS
# <?
# \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
# \Stripe\Customer::create(array(
    "metadata" => array("customer_key" => <YOUR_CUSTOMERS_KEY>)
#   "description" => "Customer for [email protected]",
#   "source" => "tok_189fT12eZvKYlo2CYj4YoHKu"
# ));
ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

// Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
// Map<String, Object> customerParams = new HashMap<String, Object>();
// customerParams.put("description", "Customer for [email protected]");
// customerParams.put("source", "tok_189fT12eZvKYlo2CYj4YoHKu");
Map<String, String> initialMetadata = new HashMap<String, String>();
initialMetadata.put("customer_key", <YOUR_CUSTOMERS_KEY>);
customerParams.put("metadata", initialMetadata);
// Customer.create(customerParams);
ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

// var stripe = require("stripe")(
//     "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
// );
// stripe.customers.create({
//    description: 'Customer for [email protected]',
//    source: "tok_189fT12eZvKYlo2CYj4YoHKu",
      metadata: {"customer_key":<YOUR_CUSTOMERS_KEY>}
// });
ADD 'metadata' containing the 'customer_key'
MAKE SURE it matches the one used with GrowSumoJS

// stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
// customerParams := &stripe.CustomerParams{
//   Desc: "Customer for [email protected]",
// }
customerParams.AddMeta("customer_key", <YOUR_CUSTOMERS_KEY>)
// customerParams.SetSource("tok_189fT12eZvKYlo2CYj4YoHKu") // obtained with Stripe.js
// c, err := customer.New(customerParams)

Depending on your integration with Stripe your interaction with the metadata could be quite different. Here is a link to the Stripe API Docs for creating a customer.

Please let us know if you have issues figuring out how to do work with metadata and we will do our best to help out.

You can now test your integration by going to the Testing Suite in the PartnerStack Dashboard. Nice work!

Product Specific Rewards using a product_key

You can reward partner's for sales of certain products by including a product_key within the charge metadata. If your PartnerStack instance is set up to listen for invoice.payment_succeeded events, you can also include this product_key in the invoice metadata instead.

  "id": "ch_1Fhd8q2eZvKYlo2CNOTs0hmB",
  "object": "charge",
  "amount": 2000,
  "amount_refunded": 0,
  "balance_transaction": "txn_19XJJ02eZvKYlo2ClwuJ1rbA",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    "email": null,
    "name": null,
    "phone": null
  "captured": false,
  "created": 1574432988,
  "currency": "usd",
  "customer": null,
  "description": "Charge for [email protected]",
  "dispute": null,
  "disputed": false,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "invoice": null,
  "livemode": false,
  "metadata": {
    // Enter product_key here 
  "payment_method": "card_1Fhd8q2eZvKYlo2CSXwtvRr1",
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": null
      "country": "US",
      "exp_month": 8,
      "exp_year": 2020,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "funding": "credit",
      "last4": "4242",
      "network": "visa",
      "three_d_secure": null,
      "wallet": null
    "type": "card"

If you aren't using PartnerStackJS

You may not be using PartnerStackJS if you have a product that is purchased on signup, for example, an e-commerce store.

If you are not using PartnerStackJS, you must attach the customer_key AND the partner_key to the metadata in your Create Charge calls to Stripe. The partner_key is a unique identifier given automatically to partners on the platform. This lets us know which partner is responsible for referring which customer.

You can find a partner's partner key in your PartnerStack dashboard under "All Partners". If you're using our referral links, we add a query parameter gspk to the URL our links redirect to. By base64-decoding the gspk parameter, you can extract the partner key from here as well.