How webhooks work

How it works

When a subscribed event occurs, a HTTP POST payload is sent to each of your configured endpoints with information about that event’s resource. Your endpoint can then perform whatever custom tasks you need, such as changing access permissions for customers, updating inventory levels, passing information to fulfilment services, or subscribing customers to mailing lists.

The JSON Webhook is the core webhook type for reacting to transaction, subscription, and customer events. You can also automate workflows with Zapier, or sync inventory with Webflow — see the Integrations section for those.

Delivery and automatic retries

This section applies to JSON webhooks. Legacy (v1) webhooks don’t follow these rules.

Respond with HTTP 200, quickly. Foxy waits up to 25 seconds for your endpoint to respond. Return HTTP 200 as soon as you’ve received the payload, then do any slow processing afterwards. Other status codes, or no response within 25 seconds, may be recorded as a failed delivery.

Failed deliveries are retried automatically. If a delivery fails, Foxy retries it roughly every 5 minutes, up to 11 more times — about an hour in total. If any retry succeeds, no further attempts are made. After the last retry, that event isn’t sent again automatically, but you can resend it yourself (see below). A failing webhook never affects the transaction itself: the payment is already processed by the time the webhook is sent.

Expect the occasional duplicate. Your endpoint can receive the same event more than once. For example, if it processed a delivery but responded too slowly or with an error, the automatic retry delivers it again. Webhooks you resend yourself carry the Foxy-Webhook-Refeed header set to true, but automatic retries don’t, so a retry looks identical to the first attempt. Use the resource’s ID (such as the transaction ID) to recognise events you’ve already handled. See Verify a webhook payload for the full list of headers.

Automatically disabled webhooks

If a webhook keeps failing with no successful deliveries, Foxy disables it automatically and sends a notification to your store’s email address. While a webhook is disabled, events aren’t sent to it and aren’t saved to send later. A webhook that has never delivered successfully can be disabled after its first failure, so make sure your endpoint returns HTTP 200 before you rely on it.

To turn a webhook back on:

1. 1

   In the Foxy admin, go to Settings > Integrations and open the webhook.

2. 2

   Turn on Enable this webhook and click Save changes.

3. 3

   Resend any events you missed while it was disabled.

Resending a webhook

In the Foxy admin, open the transaction, go to its Webhooks section, click Select, tick the webhooks you want to resend, and click Refeed. Through the API, send a POST request to the transaction’s fx:send_webhooks link. Subscriptions have the same link.

IP addresses

Current JSON webhooks are sent from these IPs:

• 54.243.60.3

• 54.152.220.165

Older (v1) JSON webhooks are not sent from static IPs.

Multiple notifications from hosted gateways

If you use a hosted gateway (where the customer is redirected to a payment page hosted by the gateway itself), each transaction may generate more than one webhook notification. Every time the IPN (Instant Payment Notification) server receives a notification from the gateway, a corresponding webhook notification is also sent.

These notifications generally arrive in order, but because they can be sent within a very short window (less than 0.5 seconds apart), network delays may cause your endpoint to receive them out of order. Account for the transaction’s status field in your logic rather than assuming arrival order — for example, don’t ship product until the status has moved from pending to approved.

Most hosted gateways send 2 notifications: one when the transaction is initiated (pending), and one when it reaches a final status (approved, declined, or rejected). There are exceptions, so test your setup with your specific gateway.

Gateways that currently use the status field this way include:

• 2Checkout

• Adyen

• Amazon

• BitPay

• Coinbase

• Comgate

• Cybersource Secure Acceptance Web/Mobile

• DIBS

• Dwolla

• MercadoPago

• Mollie

• Ogone

• PayPal Commerce Platform

• PayPal Express Checkout

• PayPal Plus

• PesaPal

• Skrill

Testing your webhook endpoint

It’s often helpful to see exactly what a webhook request looks like before pointing it at your own endpoint. Free services like Webhook.site let you generate a temporary endpoint, point your webhook at it, and inspect the full request body and headers. Similar tools include Hookbin and Requestb.in (which can also be self-hosted).

Notes

• Selling subscriptions: subscriptions can start in the future, resulting in a $0 initial transaction, and subscription modifications can also result in $0 transactions. Account for this so you don’t, for example, ship product or provision access before a subscription actually starts.