Skip to main content

​
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 retried if the merchant endpoint does not respond with a 2XX or times out. Retries are made with an exponential delay for a maximum of 7 days from the point of creation. If the request is not successful after this period then it is dropped and lost.
  • 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.
  • Caching: Webhook settings may be cached for a short period so changes may not be reflected immediately.

​
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.

​
Modifying webhooks

If you need to change a webhook subscription, for example the endpoint or authentication, it is strongly recommended that you allow for the processing of both the new and old values so that no messages are dropped. For example, if you were to update the endpoint;
  1. Merchant updates their server to process webhooks on https://new.webhooks.com
  2. Merchant updates the webhook subscription settings from https://old.webhooks.com to https://new.webhooks.com
  3. Merchant processes webhooks on https://old.webhooks.com & https://new.webhooks.com
  4. Merchant removes https://old.webhooks.com once all messages have been processed