Log inCreate a free account

Language

Log inCreate a free account
Documentation menu

Stripe: add paying customers

Add the customers who pay you through Stripe to Mailcheer automatically, with no export or import: webhook event destination, test, field mapping.

Every time a customer completes a payment on a Stripe Checkout page or through a payment link, Stripe emits a checkout.session.completed event. Stripe can send that event to a web address of your choice: that's a webhook. Point it at your Mailcheer inbound webhook URL and the customer's email lands in your contacts, with no export or import in between.

Before you start

  • A Mailcheer inbound webhook. In Mailcheer, open Integrations → Bring in contacts and click Create an inbound webhook. Mailcheer gives you an address that looks like https://mailcheer.com/api/in/<token>. Treat it as a secret and never publish it: anyone who has it can send data to it.
  • Workbench in your Stripe Dashboard. Stripe turns it on by default for new accounts. If you don't see it, enable it from the Developers settings in the Dashboard.

Paying you is not the same as agreeing to your newsletter. Only bring in people who have agreed to receive your emails. Double opt-in (a confirmation email) is on by default in Mailcheer.

1. Create the destination in a sandbox

Stripe recommends testing in a sandbox before going live. A destination belongs to the environment you create it in.

  1. In the Stripe Dashboard, open the account picker, click Sandboxes and open the sandbox you want to use.
  2. Open the Webhooks tab in Workbench.
  3. Click Create an event destination.
  4. Select Your account.
  5. Pick the API version: Stripe offers your account's version or the latest one. Write down the one you choose; you'll need it again in step 4.
  6. Under event types, select checkout.session.completed and nothing else. Stripe advises listening only to the events you actually need.
  7. Click Continue, then choose Webhook endpoint as the destination type.
  8. Click Continue and paste your Mailcheer inbound webhook URL into Endpoint URL. The description is optional; "Mailcheer" is enough to recognize it later.
  9. Click Create destination.

2. Send a test event

The quickest way is the Workbench Shell, which runs the stripe trigger command:

  1. Still in your sandbox, open the Shell tab in Workbench (Developers menu → Workbench → Shell). The Shell is read-only in live mode, so this test only works in a sandbox.
  2. Type the following command and press Enter:
stripe trigger checkout.session.completed

Stripe creates the test objects it needs, then emits the event, which goes out to your destination.

You can also pay one of your sandbox payment pages (a payment link, for example) with the test card 4242 4242 4242 4242, any future expiry date such as 12/34, any three-digit CVC, and your own email address.

Mailcheer replies right away, as Stripe requires, and processes the event afterwards. In Stripe, the destination's Event deliveries tab shows whether the delivery went through.

3. Map the fields in Mailcheer

Go back to your inbound webhook in Mailcheer: it shows what it received, along with the list of fields it found.

Stripe sends the whole event. The checkout session sits under data → object, and that is where Stripe keeps the customer's details:

  • the email address under customer_details → email (full path: data.object.customer_details.email);
  • the full name under customer_details → name.

Then click to choose:

  • the field that holds the email (required);
  • the first name and last name, if you want them;
  • tags: fixed ones (for example stripe-customer) or taken from a field;
  • double opt-in, on by default;
  • the automation to trigger, if you have one.

4. Go live

  1. Leave the sandbox and repeat the steps in part 1 in your live account, with the same Mailcheer inbound webhook URL and, where you can, the same API version: the version decides the shape of the events Stripe sends.
  2. Back in the sandbox, disable or delete the test destination from the Webhooks tab in Workbench, so your tests stop adding contacts.

To bring in customers you already had, use a file instead: see Import your contacts.

Troubleshooting

Start with what Stripe sent: Webhooks tab in Workbench → your destination → Event deliveries tab. Each event is listed as Delivered, Pending or Failed, and clicking one shows the HTTP status code of every attempt.

  • No event shows up. Check that the destination is subscribed to checkout.session.completed: Stripe only sends a destination the event types it listens to. Also check that you created it in the same environment as your test (sandbox or live), and that it isn't disabled: Stripe sends nothing to a disabled destination.
  • The delivery failed. Open the destination and compare its Endpoint URL with the inbound webhook URL shown in Mailcheer. It must be copied in full, with no extra space or character.
  • You fixed the problem. Open the event and click Resend. Stripe allows a manual resend for up to 15 days after the event was created.

Sources