Skip to content

FastSpring Webhook: 12 Events, One Signature

4 min read Notes

FastSpring Webhook: 12 Events, One Signature

A hosted checkout moves the payment out of the shop, and the webhook moves the truth back in. A fastspring webhook handler is therefore the part of a payment integration that decides whether an order is paid, refunded or still waiting.

Code: woocommerce-fastspring-gateway, GPL-2.0-or-later.

WooCommerce 8.0, WordPress 6.4, PHP 8.1, PSR-4 under GlobusStudio\WooCommerceFastSpring, no Composer in production.

The handler is a state machine

Twelve events map to WooCommerce states: order.completed marks the order paid, order.failed and order.canceled close or cancel it, return.created marks a refund.

Seven more cover the subscription: activated, canceled, deactivated, uncanceled, paused, resumed, and the two charge events that only add an order note.

The mapping table is the specification. A gateway without it is a redirect with a hopeful return URL.

Signature first, payload second

Every request is verified with HMAC SHA256 over the raw body and compared with hash_equals. The order matters: parse the payload after verification, never before, and reject on a missing header rather than treating it as a valid empty signature.

hash_equals instead of === closes the timing channel, and an optional IP filter narrows the source further. Neither substitutes for the signature.

Idempotency is not optional

A webhook may arrive twice, arrive late, or arrive before the customer’s browser returns. The handler therefore has to be safe to run more than once: check the current status before writing, and make the transition a no-op when it already happened.

That is the difference between a duplicate note and a duplicate renewal.

The order lookup

FastSpring knows its own session and order identifiers, WooCommerce knows its order id. The plugin stores the reference it needs when the session is created, so the webhook can find the order without parsing an email or guessing from a total.

A missing reference is the classic bug: the webhook arrives, the handler cannot find the order, and the payment exists on one side only.

Test mode is a domain switch

FastSpring’s test storefront is a different domain, and the plugin switches it for test mode. That keeps credentials and data separate, and it means a test payment cannot be mistaken for a real one in the logs.

Two stores, two sets of API credentials, and a webhook URL per environment. A single store used for both is a support incident scheduled for a Friday.

Logging a webhook you will read at night

Log the event name, the session reference, the order id, the signature result and the HTTP status the handler answered. Do not log the payload with customer data, and do not log the secret.

When a merchant says “the payment went through and the order is pending”, that line is the whole investigation. Without it, the next step is to reproduce a payment on a live store, which nobody wants to do at 23:00.

Log retention follows the same rule as any personal data: a week is enough to debug a weekend, and a year is a liability with no upside.

Two more lines earn their place: which plugin version handled the event, and how long it took. A handler that starts taking four seconds is a handler about to hit a gateway timeout.

What the code does not handle

Refunds initiated from the WooCommerce admin go through the API, but the policy behind them, the invoice wording and the tax treatment stay with the merchant. The plugin automates the mechanics of a hosted checkout, and the business rules remain business rules.

Related: php fingerprint library for another integration where the server has the final word, and islands architecture for a design that keeps the payload minimal.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation