> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattildapayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical webhook considerations

## 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: We will attempt to send the webhook event if the merchant endpoint did not respond with a `2XX` in the allocated time or returned a non-2XX status code. We will attempt 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 we only support one webhook configured per environment. The production and sandbox environments both support a webhook endpoint.
* Delivery promise: We currently do not provide any guarantee as to the delivery time between an event occurring in our 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 we expect an HTTP response in the 200-299 range within 5000 milliseconds.
Any unacknowledged webhooks will be retried and might cause delay in further webhook delivery.

<Warning>
  Please note that the content of a webhook event can change as we add more features. The addition of additional fields or enum values
  is not considered a backwards incompatible change. We recommend setting any JSON parser to ignore any unrecognised fields and values.
</Warning>

## Split authorization and capture

If a payment service supports delayed capture, we will always perform an authorization first even when the `intent` for a transaction is set to `capture`.
This allows us to perform various additional checks before proceeding with the capture. This also allows us the ability to hold a transaction in review.

As a consequence, this will sometimes result 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 we will automatically retry. In this situation you may
receive a `transaction.authenticated` webhook first, followed by a `transaction.captured` event.

This same order of events will happen when the `async_capture` property is set to `true` in the transaction request, as this will always handle
the capture asynchronously from the capture.