- v1.0.0-latest-prod
The webhook pattern is used by most payment gateways to communicate the results of transactions that you attempted. Typically, webhooks are used as a secondary/backup means of communicating transaction results if the normal API response failed to be received by the caller. Even though webhooks can be considered an optional feature, we strongly suggest that they’re used! They provide an extra level of assurance that transaction results will be gathered and recorded.
To use their webhooks, payment gateways typically require that you register a url with their dashboard. Once a transaction is executed, the gateway will send a request to the registered url. Most gateways leverage a retry mechanism that will continue to resend the request, until an acknowledging response is returned.
In Broadleaf’s PaymentTransactionServices, we use the same endpoint to handle webhook requests from all gateway types. This endpoint passes off to a gateway-specific service that knows how to interpret the request. From there, we look up the related PaymentTransaction and record the transaction results. We then send out an event to let other processes know that we’re now aware of transaction results. Finally, we send a response letting the webhook caller know that we successfully processed their request.
On the other hand, if anything fails throughout the processing of the webhook request, then we’ll return a response communicating the failure, which engages the webhook’s retry mechanism.
POST /webhooks/{gatewayType}
The Webhook Endpoint is used to receive and handle the asynchronous notifications from the payment gateway. It can be used, for example, to get the transaction result if it can’t be determined immediately.
To configure traffic to this endpoint, please refer to the specific documentation of your payment provider.
Responsible for identifying the relevant PaymentGatewayWebhookHandler implementation, using it to interpret the endpoint’s request headers and request body, identifying the related PaymentTransaction, & recording transaction results.
In this process, the TransactionIdentifier is used to identify the relevant PaymentTransaction. If the transaction status is SENDING_TO_PROCESSOR or AWAITING_ASYNC_RESULTS (i.e. transaction results aren’t known), then the transaction will be updated according to the PaymentResponse.
For recording the result of transactions that required 3DS verification, we create a new PaymentTransaction to record the results, and make it a child of the REQUIRES_3DS_VERIFICATION transaction.
If transaction results were recorded, then a message will be sent via the paymentTransactionWebhook topic. See DefaultTransactionWebhookMessageService and TransactionWebhookPayload.
Finally, this service is responsible for determining the endpoint response type via the relevant PaymentGatewayWebhookHandler implementation.
Responsible for ensuring the validity of the endpoint request, and building a TransactionIdentifier and a PaymentResponse from the request.
Additionally, these classes are responsible for declaring the form of a successful vs failed webhook response. For example, some gateways require a simple 200 response to declare successful processing, while others require content in the response body.
Prior to the PaymentTransactionServices 1.1.3-GA release, the Broadleaf webhook mechanisms only focused on recording results for transactions that were already known by PaymentTransactionServices. In other words, PaymentTransactionServices would have a persisted PaymentTransaction with status of SENDING_TO_PROCESSOR or AWAITING_ASYNC_RESULTS, & the webhook notifications would provide the transaction results.
With the 1.1.3-GA release, we introduced the ability for our webhooks to record manual fraud results for existing Authorize, or AuthorizeAndCapture, transactions, & the ability to record subsequent Capture and/or Refund transactions triggered from the gateway’s dashboard as part of the manual fraud review.
Additionally, with the 1.1.3-GA release, we introduced the concept of supported webhook notification types. For each PaymentGatewayWebhookHandler implementation, it must declare the set of notification types that it supports, so that the DefaultTransactionWebhookMessageService will skip attempting to handle any other types. This allows you to support different categories of notifications for each gateway, without unintentionally processing an unexpected notification. The out-of-box set of webhook notification types includes:
MANUAL_FRAUD_REVIEW_RESULTS - Webhook notifications that communicate the results of a manual fraud review.
TRANSACTION_RESULTS - Webhook notifications that communicate the results of transactions that we’re aware of - i.e. those that were triggered within PaymentTransactionServices.
THREE_D_SECURE_TRANSACTION_RESULTS - Webhook notifications that communicate the results of transactions triggered by 3DS interactions.
SUBSEQUENT_TRANSACTION_RESULTS - Webhook notifications that communicate the results of transactions that we’re not aware of - i.e. those that were triggered outside of PaymentTransactionServices.
POST /webhooks/saved-payment-method/{gatewayType}
This webhook endpoint is used to update the saved payment method if it requires some additional verification steps before it can be used.
The service that is responsible for processing saved payment method webhook requests. It uses a PaymentGatewaySavedPaymentMethodWebhookHandler implementation to read the request and update the appropriate SavedPaymentMethod.
A gateway-specific interface to assist with the interpretation & processing of payment gateway webhook requests. Implementations of this interface are used to assist with updating a saved payment method following the customer’s completion of additional verification steps.