Falcon Payments can handle 2 webhooks out of the box.
handlePaymentUpdateThis is normally triggered by the payment provider when a payment is updated.
Payment Provider -> Falcon Payments -> Shop.
handleOrderUpdateThis is normally triggered by your shop and is used when an order is updated.
Shop -> Falcon Payments -> Payment Provider.
Payment Updated Webhook
This webhook sends data from your payment provider to your shop.
The basic flow is:
- Pass webhook URL to your payment provider when creating your order / payment intent.
- The payment provider triggers the webhook when a payment is changed within their system.
- The webhook triggers
onPaymentUpdatedin your payment provider package.
- This returns
PaymentWebhookResultand causes the
PAYMENT_STATUS_UPDATEDevent to be emitted.
- Your shop endpoints package listens for the
- This then triggers a method in your shop API (
onPaymentStatusUpdatedin our core API packages).
An example use-case for this is if a payment status changes within the payment provider you may want this information to be passed to your shop.
The webhook URLs are configured in your
In this case the webhook URL would be
webhookBaseUrl should be pointed at your falcon server instance. If you're running your app on cloud your URLs will be proxied for you so your sites main domain is fine.
To configure this on a remote environement you can use the variable
The webhook URL needs to be accessible so you can't use localhost. we recommend using a service like ngrok on your Falcon server instance and setting the
webhookBaseUrl to point to that. Once you've installed ngrok it should be as simple as running
ngrok http 4000. Provided Falcon Server is running on port 4000 this will return you an
https URL you can use.
provider- The payment provide code, e.g.
mollie. This is used so we know which provider should handle the
context- This webhook comes from your payment provider so we pass the entire HTTP request
onPaymentUpdatedmethod, such that query and body data can be extracted.
This method should return
Subscribing to PAYMENT_STATUS_UPDATED
To subscribe to the
PAYMENT_STATUS_UPDATED event emitted by your payment provider package you'll need to add this code to your shops endpoint package.
This example will trigger the
onPaymentStatusUpdated in your shops API where the payload is
Order Update Webhook
This webhook sends data from your shop to your payment provider.
- The webhook URL is configured in Falcon Server
- The webhook URL is sent to your shop when placing an order
- The shop triggers the webhook when an order is updated (usually
- This triggers a method in your shop API (
- This triggers a method in your payment provider API (
- Depending on the
status: OrderStatusprovided different methods are triggered e.g. refund.
An example of this is if an order is marked as shipped in your shop, you may want to update it in your payment provider. Other examples include refunded orders and shipment tracking being added.
Boolean - depending on if the update was successful or not.