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

When a webhook is triggered, the system waits 1 minute for a response from your endpoint. If it doesn’t receive an HTTP 200 response in that time, it automatically retries up to 11 more times within the following hour. Retries get progressively further apart over that hour, ranging from around 1 minute apart up to around 10 minutes apart. If any retry succeeds, no further attempts are made.

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.