Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

In certain scenarios, when the intent for a transaction is set to capture, the system splits the operation into a separate authorization and capture. This means the payment is first authorized with the payment service, and then captured in a subsequent request. A capture is split into two operations when all of the following conditions are met:
  1. The transaction intent is set to capture.
  2. The payment service (connector) supports delayed captures.
  3. The payment method is a card and is not using an alternative payment scheme.
  4. At least one of the following is true:
    • The payment service does not support direct capture (sale).
    • The anti-fraud decision for the transaction was review.
    • Gift cards were used as part of the transaction (multi-tender).
When a transaction is split, the authorization is performed first because it is the most likely step to fail. If the authorization succeeds, the capture follows automatically. If any additional step fails (for example, gift card redemption), the authorization is voided instead of requiring a refund. As a consequence, this sometimes results in multiple webhooks per transaction. In a normal situation, you would only receive a transaction.captured event, but when a capture is split you may receive a transaction.authorized 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.

​
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