Mastering ESHOPMAN Payment Webhooks: Avoiding the Double Prefix Pitfall for Custom Providers

At Move My Store, we understand the intricacies of building robust e-commerce solutions with ESHOPMAN. A common challenge developers face when integrating custom payment providers involves correctly configuring payment webhooks. This community insight sheds light on a critical misconfiguration pitfall that can lead to silent payment failures and stalled orders within your ESHOPMAN storefront, especially for asynchronous payment methods.

ESHOPMAN, as a headless commerce platform built on Node.js/TypeScript and deeply integrated with HubSpot for storefront management and CMS deployment, relies heavily on accurate webhook communication for seamless order processing. When setting up a custom payment provider using the ESHOPMAN Admin API, developers often refer to various guides. However, a subtle inconsistency in guidance regarding webhook URLs can cause significant headaches.

The Double 'pp_' Prefix Predicament

The core of the issue stems from how ESHOPMAN’s internal payment module processes incoming webhook requests. Some internal documentation might suggest pointing your custom provider's webhooks at the full registered provider id, which typically includes a pp_ prefix, like pp_myprovider_myprovider. This seems logical, as pp_… is the format seen for provider IDs across the ESHOPMAN Admin API and database.

However, the ESHOPMAN payment module's internal service, specifically the PaymentModuleService.getWebhookActionAndData function, automatically adds the pp_ prefix to the incoming provider identifier. This leads to a double prefixing error:

async getWebhookActionAndData(eventData, sharedContext) {
    const providerId = `pp_${eventData.provider}`;
    return await this.paymentProviderService_.getWebhookActionAndData(providerId, eventData.payload);
}

If your webhook URL is configured as /hooks/payment/pp_pagbank_pagbank, the system internally attempts to resolve a provider with the ID pp_pp_pagbank_pagbank. Since no such provider exists, the resolution fails with an AwilixResolutionError. The system then retries the event several times before silently dropping it.

Silent Failures and Stalled Orders

One of the most frustrating aspects of this issue is its silent nature. From the perspective of the payment provider, the webhook delivery appears successful, returning a 200 OK response. This means your payment provider's dashboard will show successful deliveries, while in reality, no payment updates are being processed within ESHOPMAN. For asynchronous payment methods such as PIX, boleto, or OXXO, this is critical: orders remain perpetually in an 'awaiting' state, never transitioning to 'paid' or 'fulfilled' in your HubSpot-managed storefront.

The Correct ESHOPMAN Webhook Configuration

Fortunately, the solution is straightforward and aligns with the official ESHOPMAN documentation for payment webhook events. When configuring your custom payment provider's webhook URL, you must use the identifier without the initial pp_ prefix.

For a custom provider registered with static identifier = "myprovider" and id: "myprovider", the correct webhook endpoint should be:

POST /hooks/payment/myprovider_myprovider

This ensures that when the ESHOPMAN payment module adds its internal pp_ prefix, the resulting ID (e.g., pp_myprovider_myprovider) correctly matches your registered custom payment provider.

Best Practices for ESHOPMAN Developers

• Consult Official ESHOPMAN Documentation: Always prioritize the official ESHOPMAN documentation for API routes and configuration details, especially for critical integrations like payments.
• Thorough Testing: Implement comprehensive testing for your custom payment provider integrations, including end-to-end tests for webhook processing and order status updates in your ESHOPMAN Admin and HubSpot storefront.
• Monitor Logs: Regularly monitor your ESHOPMAN server logs for any AwilixResolutionError or messages indicating failed event subscribers, particularly after payment webhook receipts.

By understanding this nuance in ESHOPMAN payment webhook configuration, developers can avoid common pitfalls, ensure reliable payment processing, and maintain a seamless customer experience across their HubSpot-deployed storefronts. Move My Store is committed to helping you navigate these technical details to optimize your ESHOPMAN headless commerce operations.