Webhooks
  • 13 Jul 2022
  • 5 Minutes to read
  • Dark
    Light

Webhooks

  • Dark
    Light

Overview

Webhooks provide a mechanism where a server-side application (In this case Stripe) can notify a client-side application (in this case Payments) when a new event (like customer create, update, delete, charge capture, charge failed, etc) has occurred on the server.

Webhooks automatically send specified data to a destination (endpoint) from database events. Our Payments app utilizes webhooks for many of our features, such as updating your Salesforce org with credit card information and creating Dispute records.

Benefits

  1. Webhook allows us to stay up-to-date by updating the card on file with any recent changes in the credit card information by major credit card companies.
  2. Allow Payouts to be received in Salesforce.
  3. After capturing the transaction, webhooks allows disputes to be created in Salesforce.
  4. Notifies/updates of any deleted payment gateway customer record or payment method.
  5. Recognize any changes in Stripe Billing subscription/Invoices.
  6. Maintains consistency of all records from Stripe into Salesforce and so on.

Instructions

Create a Force.com Domain

  1. Within Setup In the Quick Find menu, type in and click Sites.
  2. If a Force.com domain has not been set up continue with the instructions, otherwise navigate to the steps for configuring a Site below.
  3. Enter a value for your Force.com domain and click Check Availability.
  4. Accept Site terms of use and click Register My Force.com Domain.

Site Configuration

  1. Click New next to Sites.
  2. Set a Site LabelSite Name, and Default Web Address (We suggest using webhook or stripe).
  3. Check the Active checkbox.
  4. On the active Site home page field click the Lookup icon and select In Maintenance (the page is not visible, it's just a placeholder because a value is required).
  5. Check Require Secure Connections (HTTPS).
  6. Click Save.

H_02_21_site config

Assign the Blackthorn | Payments (Site Guest User) permission set to the public user

Site Guest User Permission Set Renamed

For users looking to setup Webhooks with a Payments package older than v5.6 you will need to add the Blackthorn | Payments (Webhooks) permission set. Additionally, you will need to add a Sharing Rule to allow the Site Guest User to access the Payment Gateway object.

The Blackthorn | Payments (Site Guest User) permission set is now a dual purpose permission set with packages v5.6 and beyond. This permission set will be used for webhook setup and REST API setup.

  1. Navigate back to the Site you created.

  2. Click on the Public Access Settings button.
    H_02_21_assign site guest user per 1

  3. Click on the View Users or Assign Users button.

  4. Click on the link for the site guest user.
    H_02_21_assign site guest user per 2

  5. Add the Blackthorn | Payments (Site Guest User) permission set to this user's record.

Not seeing the Blackthorn | Payments (Site Guest User) Permission Set?

This permission set is only available in Payments packages 5.16 and later. Please upgrade to the latest version then try again.

  1. Click Save.
    H_02_21_assign site guest user per 3

Configure Webhooks and Add Webhook Events

Configure Webhook in Stripe

  1. Navigate to your connected Stripe account dashboard.If you are creating a Webhook URL for your Stripe account in test mode, make sure the "Viewing test data" switch is on.
    H_02_21_configure webhook in stripe 1

  2. Select the Developers tab on the left-hand side.

  3. Click the Webhooks tab and select Add endpoint.

  4. In the Endpoint URL field you need to set the URL to the Salesforce webhook site you just created. You'll need to replace the 3 upper-case values with your org values in this URL:https://SITE_DOMAIN_NAME/SITE_PATH/services/apexrest/bt_stripe/webhook/WEBHOOK_LABEL

SITE_DOMAIN_NAME = The Salesforce Domain Name for the site you setup. To get this value, navigate to the Site record and look at the Custom URLs related list. Use the Domain Name value.

If you see more than 1 domain name, always use the one with secure in the name - these domains use https which is required by Stripe.

H_02_21_configure webhook in stripe 2

SITE_PATH = The Path for the Site. Use the Path value from the Custom URLs related list of the Site. (Refer above screenshot)

WEBHOOK_LABEL = To get this value, navigate to the Payment Gateway record you want to use. Then copy the value from the Webhook Label field.

H_02_21_configure webhook in stripe 3

So for the images above, your webhook URL would be: https://adminmethods.secure.force.com/stripe/services/apexrest/bt_stripe/webhook/test

If you have multiple Stripe accounts connected to your Salesforce org, and want to create Webhook Endpoint for each in Stripe, you can use the same Salesforce Site - you just need to change WEBHOOK_LABEL part of the Url to the Webhook Label value of the Payment Gateway record you want to use.

  1. In Events to Send, click "receive all events" and Add endpoint.
    H_02_21_configure webhook in stripe 4

Configure Webhook in Auth.net

  1. Navigate to your connected Auth.net account dashboard.

  2. Click on Account tab | Settings | Webhooks.
    H_02_21_configure webhook authdot 1

  3. Click Add endpoint.

  4. Define a Name.

  5. Follow Step 4 from above to generate the Endpoint URL field.

  6. Set Status = Active.

  7. Under Select Events, check All Events and click Save.
    H_02_21_configure webhook authdot 2

If you have multiple Auth.net accounts connected to your Salesforce org, and want to create Webhook Endpoint for each in Auth.net, you can use the same Salesforce Site - you just need to change WEBHOOK_LABEL part of the Url to the Webhook Label value of the Payment Gateway record you want to use.

Test Webhook Connection

Test webhook connection in Stripe

Verifying in Test Mode:

  1. Select the Webhook tab on the left-hand side.

  2. Click on your URL.

  3. In the top right, click Send Test Webhook.
    H_02_21_test webhook connection 1

  4. Event Type: "Customer.created" and click Send Test Webhook.If you received a "Test webhook sent successfully" message, then Webhooks are set up correctly!
    H_02_21_test webhook connection 2

Test webhook connection in Authorize.net

  1. Click on Account tab | Settings | Webhooks.
  2. Edit Endpoint and flip the status to "Inactive" and click Save.

You will see a Test Webhook button as shown in the below screenshot.

H_02_21_test webhook connection 3

If you received a "Ping successful" message at the top, then Webhooks are set up correctly!

Verifying in Live Mode

In live mode, don’t forget to create a new URL. You can copy your Test Webhook URL, and update the Webhook Label from your live Payment Gateway record.

  1. Create a new Customer in Stripe.
  2. Click on the newly created customer record, scroll down to Events, and select the Event record.
  3. Scroll down to Webhooks.

If the Webhook record says "Success", then Webhooks are set up correctly in Production.

H_02_21_verify live mode

Adding Webhook signatures in Stripe (optional)

Webhook signatures is an additional layer of security. When setting them up, the system makes sure that the webhook event messages are not corrupted in Salesforce.

  1. Go to Stripe Dashboard | Webhooks.

  2. Select the webhook.

  3. On the Signing Secret section click Click to Reveal.
    H_02_21_add webhook sig stripe 1

  4. Navigate in your Salesforce Org to Setup | Custom Metadata Settings.

  5. Click Webhook Secret | Manage Records

  6. Click New.

  7. Enter values for LabelWebhook Secret Name, and Signing Secret.

  8. Click Save.
    H_02_21_add webhook sig stripe 2

Next Steps

Troubleshooting

If you have received an error in the Setup Wizard, with Webhooks or have a question, please view our Troubleshooting page.