About Webhook Events
A Webhook Event record logs changes that a user makes in Stripe. The changes can be creations, updates, or deletions. For example, if a user updates a Payment Method in Stripe, Blackthorn Payments creates a Webhook Event record in Salesforce, and the following batch job then updates the related Payment Method record in Salesforce.
Stripe uses webhooks to push information from Stripe to Salesforce; however, Stripe pushes the webhooks to Salesforce randomly. For example, payment data may be pushed before customer data. That is an issue because Salesforce needs to receive the information in this order: Stripe Customer, Payment Method, and Transaction.
To mitigate Stripe's unpredictable order, we place all these records in Webhook Event records and process them in a batch.
We suggest using Webhook Event records for troubleshooting and/or tracking which records have been created or updated in Salesforce. The Webhook Event object only captures data from Stripe; it does not send information back to Stripe. Updating or creating Webhook Events in Salesforce will not create and/or update records in Stripe.
There are two ways to process Webhook Events: single-batch processing or queueable processing.
Single-Batch Processing: Webhooks are processed one-at-a-time within a single batch transaction. Resources are shared within the Stripe transaction.
Queueable Processing: Each Webhook Event has its own Stripe transaction and governor limits, rather than sharing resources.
Prerequisite
You must configure webhooks before Webhook Events can be created.
Single-Batch Processing
Each Webhook Event record contains the full Stripe JSON payload describing what occurred. The record is processed in Salesforce by a scheduled batch job that processes new records every 5 minutes. The batch job parses the Webhook Event details and uses the data to insert or update the related record in Salesforce.
The following two fields in the Blackthorn | Payments Trigger Settings custom settings will help you manage single-batch processing of Webhook Event records.
The Retain Webhook Records for (Days) (bt_stripe__Retain_Webhook_Records_for_Days__c) field controls how long processed Webhook Event records are stored in your org. The default value is blank or null. If left blank, processed records are not deleted and can accumulate indefinitely, contributing to the volume issues.
Entering a number other than zero, ensures that processed Webhook Events whose Created (bt__stripe_Created__c) date is older than the configured number of days are deleted. For example, if Retain Webhook Records for (Days) is set to “30,” processed Webhook Events older than 30 days will be automatically purged.
A value in the Webhook Batch Delay Minutes (bt_stripe__Webhook_Batch_Delay_Minutes__c)) field adds a time delay filter to the webhook processing query. The delay allows other processes time to finish and prevents duplication of records when Webhook Events process prior to receiving API responses back from the Payment Gateway.
If this field is set to X number of minutes,
existing Webhook Events created more than X minutes ago will be processed.
new Webhook Events will be processed after X minutes have passed.
The default value is blank (null), allowing Webhook Events to be processed immediately after they are created.
Manually Process a Webhook Event record
Sometimes you may need to process a Webhook Event faster than every 5 minutes when the scheduled job occurs. That’s when manually processing a Webhook Event is an option.
To manually process a Webhook Event record, complete the following steps.
Open a Webhook Event record.
Click the Process button at the top of the page. (It may be in the drop-down menu accessed via the down arrow in the upper right-hand corner.)
Queueable Processing
A new queueable processing path for Webhook Events provides customers with an alternative to the existing single batch processing. With the queueable process, each Webhook Event has its own Stripe transaction and governor limits, rather than sharing resources.
This process gathers a group of Webhook Event records, processes the first one, and chains a new instance with the remaining list, allowing the Webhook Events to be processed quickly. Once the process meets its queueable max limit, the existing batch scheduler absorbs the remaining unprocessed Webhook Events.
Now, the process reviews the Blackthorn Pay - Trigger Settings custom setting’s Webhook Use Queueable (bt_stripe__Webhook_Use_Queueable__c) field.
If Webhook Use Queueable is unchecked (default) or “off,” then all records in a batch are processed in a single call and share governor limits.
If Webhook Use Queueable is checked (i.e., “on”), the new queueable processing method is used. Here, each Stripe webhook gets its own transaction with independent governor limits. Non-Stripe webhooks are unaffected and are immediately marked as processed.
In addition to the main on/off toggle, there are four additional fields on the Blackthorn Pay - Trigger Settings custom setting that you can use to customize the process.
The Webhook Max Queueable Retry (bt_stripe__Webhook_Max_Queueable_Retry__c) field determines the maximum number of retries for a failed Webhook Event before marking it as permanently processed. For example, if Webhook Max Queueable Retry = “1,” after the webhook fails the first time, it is retried once more. If Webhook Max Queueable Retry = “0,” no retries will occur, and the record is marked as. If the field is empty, it defaults to “1.”
The Webhook Batch Scope Size (bt_stripe__Webhook_Batch_Scope_Size__c) field controls how many records each batch execute call receives. If the field is empty, it defaults to “1.”
The Webhook Reschedule Minutes (bt_stripe__Webhook_Reschedule_Minutes__c) field specifies the number of minutes between the completion of one webhook batch and the start of the next. The default value is “5.”
The Webhook Query Filter (bt_stripe__Webhook_Query_Filter__c) field contains a custom WHERE clause for the webhook query. When populated, it replaces the default filter (Processed__c = false AND Process_Async__c = false). Leave the field empty to use the default filter. WARNING: This field accepts raw SOQL fragments that are appended directly to the query. Administrators are responsible for ensuring the value is a valid and safe SOQL condition. Incorrect or malformed input will cause batch processing to fail.
Toggle Between the Default and Queueable Webhook Processing
Go to Setup.
In the Quick Find box, enter and click “Custom Settings.”
Locate “Blackthorn Pay - Trigger Settings” and click Manage.
Click Edit.
Check the Webhook Use Queueable checkbox.
Customize the following fields as needed.
Webhook Max Queueable Retry (max retries for a failed Webhook Event before it is marked as processed.)
Webhook Batch Scope Size (how many records each batch cycle claims)
Webhook Reschedule Minutes (interval between batch runs)
Click Save.
You can toggle the Webhook Use Queueable checkbox on and off at any time. Unprocessed Webhook Events will be picked up by whichever path is active on the next batch execution cycle.
View Stripe Webhooks and Salesforce Webhook Events
Stripe Webhooks
Use the steps below view webhooks in your Stripe account.
Navigate to your Stripe dashboard.
On the left-hand side, click on "Events and Logs". This is where you will see the webhooks.
Click on a record.
The record is split into event details, event data, and webhooks.
Salesforce Webhook Events
Follow the steps below to open a Webhook Event record in Salesforce.
Go to Setup.
In the App Launcher, enter and click “Webhook Events.”
Select a record.
Relevant Fields
The following fields on the Blackthorn Pay - Trigger Settings custom setting allow users to configure how Webhook Events are processed.
Field Label: Retain Webhook Records for (Days)
API Name: bt_stripe__Retain_Webhook_Records_for_Days__)
Data Type: Number(2, 0)
Default: Null
Help Text: Controls how long processed Webhook Event records are stored in your org. If blank, processed records are not deleted and can accumulate indefinitely.
Field Label: Webhook Batch Delay Minutes
API Name: bt_stripe__Webhook_Batch_Delay_Minutes__c
Data Type: Number
Default: null
Help Text: The number of minutes by which the webhook process is delayed. The delay allows other processes time to finish and prevents duplication of records.
Field Label: Webhook Use Queueable
API Name: bt_stripe__Webhook_Use_Queueable__c
Data Type: Checkbox
Default: Unchecked
Description: When enabled, Stripe webhook events are processed via a chaining Queueable instead of inline batch execution. Non-Stripe webhooks are unaffected.
Help Text: Toggle between batch inline processing (off) and queueable chaining (on) for Stripe webhooks.
Field Label: Webhook Max Queueable Retry
API Name: bt_stripe__Webhook_Max_Queueable_Retry__c
Data Type: Number
Default: 1
Description: Maximum number of retries for a failed webhook event in queueable mode before marking it as permanently processed. Only applies to the queueable processing path (Webhook_Use_Queueable__c = true). A value of 1 means the webhook is attempted once and retried once on failure; a value of 0 means no retries — a single failure marks the record as processed. Defaults to 1 when empty.
Help Text: Max retries for failed webhooks before marking as processed. Defaults to 1.
Field Label: Webhook Batch Scope Size
API Name: bt_stripe__Webhook_Batch_Scope_Size__c
Data Type: Number
Default: 1
Description: Scope size passed to Database.executeBatch for webhook processing. Controls how many records each batch execution call receives. Defaults to 1 when empty.
Help Text: Batch scope size for webhook processing. Defaults to 1.
Field Label: Webhook Reschedule Minutes
API Name: bt_stripe__Webhook_Reschedule_Minutes__c
Data Type: Number
Default: 5
Description: Number of minutes to wait before rescheduling the webhook batch in the finish method. Defaults to 5 when empty.
Help Text: Minutes until the next webhook batch is scheduled after completion. Defaults to 5.
Field Label: Webhook Query Filter
API Name: bt_stripe__Webhook_Query_Filter__c
Data Type: Text
Description: Custom WHERE clause condition for the webhook query. When populated, replaces the default filter (Processed__c = false AND Process_Async__c = false). Leave empty to use the default filter. WARNING: This field accepts raw SOQL fragments that are appended directly to the query. Administrators are responsible for ensuring the value is a valid and safe SOQL condition. Incorrect or malformed input will cause batch processing to fail.
Help Text: Custom WHERE clause for webhook query. Leave empty for default: Processed__c = false AND Process_Async__c = false
Troubleshooting/FAQ
If you have received an error with any Webhook Event record or have a question, please view our Troubleshooting or FAQ page.