Endpoint URL
The webhook subscription endpoint URL configured to receive the webhooks should be a
HTTPS endpoint that supports TLS 1.2. Please ensure your Web Application Firewall (WAF)
does not block the webhook requests.
Webhook logic
- Response time: The endpoint URL configured to receive the webhooks should return an HTTP response in the 200-299 range within 5000 milliseconds.
- Retry: The webhook event is attempted to send if the merchant endpoint did not respond with a
2XX in the allocated time or returned a non-2XX status code. Attempts are made for up to 3 days. Due to the retry behavior, you might receive an event more than once if a timeout has occurred. You might also never receive an event if no successful delivery was possible in the 3-day window.
- Number of webhook endpoints: Currently only one webhook is supported configured per environment. The production and sandbox environments both support a webhook endpoint.
- Delivery promise: Currently no guarantee is provided as to the delivery time between an event occurring in the system and it being delivered via a webhook to the merchant.
Acknowledging webhooks
When you receive a webhook event, you should always acknowledge its receipt, even if it contains additional information. To acknowledge a webhook, an HTTP response in the 200-299 range within 5000 milliseconds is expected.
Any unacknowledged webhooks are retried and might cause delay in further webhook delivery.
Please note that the content of a webhook event can change as more features are added. The addition of additional fields or enum values
is not considered a backwards incompatible change. Setting any JSON parser to ignore any unrecognized fields and values is recommended.
Split authorization and capture
If a payment service supports delayed capture, an authorization is always performed first even when the intent for a transaction is set to capture.
This allows performing various additional checks before proceeding with the capture. This also allows the ability to hold a transaction in review.
As a consequence, this sometimes results in multiple webhooks per transaction in case the first capture fails. In a normal situation, you would
only receive a transaction.captured event, but in case of a failure to capture, an automatic retry is performed. In this situation you may
receive a transaction.authenticated webhook first, followed by a transaction.captured event.
This same order of events happens when the async_capture property is set to true in the transaction request, as this always handles
the capture asynchronously from the capture.
