# Webhooks

Paytree provides webhook support to keep you informed of payment status updates. When important events occur— such as changes in payment status, failed attempts, or successful transactions—we will send relevant data to the callback URL you specify.

It is essential to implement webhook handling on your server to receive these updates in real time. This will allow you to keep your system in sync with payment events and take appropriate actions based on the information received.

Ensure that your callback URL is publicly accessible and capable of securely processing the incoming webhook data. Proper handling of webhooks is critical to maintaining a smooth payment process and ensuring your system stays up-to-date.

### Callback Flow

Paytree webhooks allow you to receive real-time payment updates by sending data to the callback URL you specify. The flow is as follows:

1. **GET Request to Callback URL**: Paytree sends a GET request to the callback URL you provide, containing key parameters like **Payment Intent ID** and **Transaction ID**.
2. **Extract Parameters**: You need to extract the **Payment Intent ID** and **Transaction ID** from the request to identify the relevant payment.
3. **Lookup Payment Details**: Use the **Payment Intent ID** to make an API request to Paytree, retrieving the latest payment information and status.

You must respond with a HTTP status code of **200**. Any other status code will result in a total 10 consecutive retry attempts, spaced 30 seconds apart.

Adhering to this flow ensures your system is up-to-date with the latest payment data and status changes.

<figure><img src="/files/aW1CRGYllU6LFJGF7KzI" alt="" width="375"><figcaption><p>Overview of webhook notification process flow</p></figcaption></figure>

### Callback URL Tags

When setting up your callback URL for Paytree webhooks, you can use special tags to dynamically represent key values such as the **Payment Intent ID** and **Transaction ID**. These tags are replaced by Paytree with the actual data when sending the webhook request.

* **{payment\_intent\_id}**: This tag represents the **Payment Intent ID** that Paytree generates when you create a payment intent. You will need to use this ID to perform the lookup for the latest payment details.
* **{transaction\_id}**: This tag represents the **transaction\_ref** that you provide when creating a payment. This will be included in the webhook data to help you match the payment with your system.

You can place these tags in your callback URL, and Paytree will automatically replace them with the corresponding values in the webhook request. For example, your callback URL might look like this:

```
https://yourdomain.com/payment-update?payment_intent_id={payment_intent_id}&transaction_id={transaction_id}
```

When the webhook is triggered, Paytree will replace the tags with actual values, so the resulting URL might look like this:

```
https://yourdomain.com/payment-update?payment_intent_id=76460612-27a6-40a3-ad1a-7da0b758f563&transaction_id=txn_abc123
```

### Retries

In the event where you return a status code which is not 200, we will attempt a total of 10 retries, first one 30 seconds after the initital failure and all subsequent ones 60 seconds apart.

| Retry Attempt | Time after Previous Attempt (in seconds) | Retry Timestamp                  |
| ------------- | ---------------------------------------- | -------------------------------- |
| 1st Retry     | 30                                       | **January 1, 2024, 12:00:30 PM** |
| 2nd Retry     | 60                                       | **January 1, 2024, 12:01:30 PM** |
| 3rd Retry     | 60                                       | **January 1, 2024, 12:02:30 PM** |
| 4th Retry     | 60                                       | **January 1, 2024, 12:03:30 PM** |
| 5th Retry     | 60                                       | **January 1, 2024, 12:04:30 PM** |
| 6th Retry     | 60                                       | **January 1, 2024, 12:05:30 PM** |
| 7th Retry     | 60                                       | **January 1, 2024, 12:06:30 PM** |
| 8th Retry     | 60                                       | **January 1, 2024, 12:07:30 PM** |
| 9th Retry     | 60                                       | **January 1, 2024, 12:08:30 PM** |
| 10th Retry    | 60                                       | **January 1, 2024, 12:09:30 PM** |

In the event of a longer outage, where you were unable to capture any events sent by us (Including all retries); it's possible to query the payment intent or payment endpoints to retreieve up to date information about the transactions in question.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://paytree.gitbook.io/api/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.