Testing Webhooks in Stripe Subscription Payments

This tutorial/guide will show you how to connect webhooks, add customers, add cards, create/add invoices, and charge invoices. If you came to this guide to find out how to do one of those, you may scroll down to find the topic you are looking for. Otherwise, this guide is a complete guide or tutorial of how to connect and test webhooks in Stripe using any programming language of your choice. There are examples included as well.

There comes a time where you may want to your webhooks in your Stripe account. In this tutorial, we will be using PHP. We’re going to show you how to test your webhooks using PHP – specifically the invoice.payment_failed webhook for subscriptions.

First, you’re going to want to set up web your webhook on your website/server. Let’s pretend that my webhook is located at: https://www.example.com/lib/stripe/webhook.php.

require_once $_SERVER['DOCUMENT_ROOT'].'/vendor/autoload.php'; // Load Stripe components via Composer

\Stripe\Stripe::setApiKey("secret key"); // Your Stripe API Secret Key

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

$event = \Stripe\Event::retrieve($event_json->id);

if(isset($event) && $event->type == "invoice.payment_failed") {
	$customer = \Stripe\Customer::retrieve($event->data->object->customer);
	$customerEmail = $customer->email;
	echo $customerEmail;

	$stmt = $dbh->prepare("UPDATE users SET subscription = 1 WHERE email = :email");
	$stmt->bindParam(':email', $customerEmail);
	$stmt->execute();
}

We first get the request from Stripe and we parse it as JSON. Then we decode the JSON and we get the event ID from the JSON.

In our if statement, we are checking to see if the event ID was found ($event) and we are checking for the event type invoice.payment_failed.

If both of those checks succeed in the if statement, we proceed to get the customer object using \Stripe\Customer::retrieve.  This will contain all the information of the customer who’s invoice payment failed. From there, we can get the customer’s email.

We can then do whatever we need to do in the database. In this case, I am updating the subscription plan of the user in my database. I am resetting their plan back to 1 (which is the free plan on my site) when they fail to pay an invoice.

Connecting the Webhook to Stripe

Now that we have our webhook, we have to add our webhook to Stripe so Stripe will know where to send the information to.

You’re going to want to login to your Stripe account and click on API on the left sidebar. Then at the top, click on the Webhooks tab. Then you want to click on the Add endpoint button on the top right.

Here is a screenshot to make things easier:

Now we’re ready to test our webhook.

Add a Customer

We are going to need to add a customer to our Stripe test/sandbox account. To do so, click on Customers on the left sidebar. Then click on the New button at the top right.

Here is another screenshot of how to do so:

Then enter an email and description for your new “test” customer.

Add Cards in Stripe

To testing your webhook in Stripe, we have to simulate a Stripe webhook event type. In this case, we have to simulate a webhook called invoice.payment_failed.

We have to start by clicking on the customer in the Customers page. Go to the section that says Cards and click on Add card. For the card number, type enter 4000 0000 0000 0341. This card number is a card that will decline when you try to charge it. In our use case, it is good because we are trying to simulate the invoice.payment_failed event. For the CVC, expiration date, and expiration month, you can enter anything. After you are done entering the card information, you may click Add card.

Add Invoice in Stripe

You are going to want to add a invoice to test the webhook. To do that, you want to scroll down to the section that says Pending invoice items and click on the button next to it that says Add invoice item.

After you click on the Add invoice item button, enter the following information. Leave currency to your preferred currency, set the amount to any random amount (i.e. $10.00), set the description to anything, and select “Auto (next to be billed)” under Subscription. Then click the Create invoice item button.

Charge Invoice and Test Webhook Event

To charge the invoice now or immediately, click on the Invoice now button.

Now click on the invoice that you just invoiced under Invoices. It should say “UNPAID” beside it.

After you have clicked on the invoice item, you will be taken to an invoice page.

It should say something like this: “Invoice payment failed”. “Your card was declined.”

Now, go back to your customer’s page and scroll down to the Events section. Then click on the event that says “<email>’s invoice for <amount> failed payment”.

Then scroll down to Webhooks and view the webhook information there.

If you are updating the database in your webhook.php file, your database should be updated now.

This is a simple tutorial on how to test your webhook in Stripe. Good luck to everyone!