# Webhooks

When building IVPAY integrations, you might want your applications to receive events as they occur in your IVPAY accounts, so that your back-end systems can execute actions accordingly.

To enable webhook events, you need to register a webhook endpoint on IVPAY's merchant dashboard: 

1. Go to [IVPAY Merchant Dashboard](https://app.ivpay.io) and login
2. Go to "Points of Sale" and click on the API Key you want to enable webhook events 
3. Add the endpoint URL to the "Webhook URL" field
4. Save!

After registering it, IVPAY can push real-time event data to your application’s webhook endpoint. IVPAY uses HTTPS to send webhook events to your app as a JSON payload.

Receiving webhook events is particularly useful for listening to asynchronous events such as when IVPAY confirms a payment.

{% hint style="info" %}
Webhook is a kind of feedback method for payment information. When payment status changes, a POST request is sent to the callback URL specified beforehand.
{% endhint %}

## Authentication

All the events are sent with the following headers:

```json
{
    'Content-Type': 'application/json', 
    'X-API-KEY': 'api_key'
}
```

The \`X-API-KEY\` field can be used to validate the event by matching it with the API Key you obtained in the merchant dashboard (instructions [here](https://docs.ivpay.io/start/get-started/guides/obtaining-api-keys)).

## Event types

There are 4 types of events:

* [Payment CREATED](#payment-created-event)
* [Payment PENDING](#payment-pending-event)
* [Payment PAID](#payment-paid-event)
* [Payment TIMEOUT](#post-payment-timeout-event)

All the details of each event can be seen below. 

## Notification attempts

All webhook requests to IVPAY must respond with an HTTP 200 status code to indicate success. Any other status or a missing response will be treated as a failure. IVPAY will attempt to deliver up to 3 events (every 5 seconds). 

In summary, this is what happens when the merchant replies to IVPAY webhook notification with the following HTTP status codes:

* **200** → IVPAY considers the notification successfully delivered so it stops
* **Any other code** → IVPAY resends the notification following the above rules

This ensures reliable delivery of notifications while avoiding excessive retries.

You can see the webhook events log on the [IVPAY Merchant dashboard](https://app.ivpay.io/pos) for debugging purposes.

## `POST` Payment CREATED event

As an example, here you can see what a payment CREATED looks like:

### Headers

```
{
    'Content-Type': 'application/json', 
    'X-API-KEY': 'api_key'
}
```

### Body

```json
{
    "payment_id": "6b577835afbefe60335b6e5cd04410a9",
    "status": "CREATED",
    "foreign_id": "123456",
}
```

## `POST` Payment PENDING event

As an example, here you can see what a payment PENDING looks like:

### Headers

```json
{
    'Content-Type': 'application/json', 
    'X-API-KEY': 'api_key'
}
```

### Body

```json
{
    "payment_id": "6b577835afbefe60335b6e5cd04410a9",
    "status": "PENDING",
    "processed_at": 1726248785,
    "foreign_id": "123456"
}
```

## `POST` Payment PAID event

As an example, here you can see how a payment PAID looks like:

### Headers

```
{
    'Content-Type': 'application/json', 
    'X-API-KEY': 'api_key'
}
```

### Body

```json
{
    "payment_id": "6b577835afbefe60335b6e5cd04410a9",
    "status": "PAID",
    "processed_at": 1726248785,
    "foreign_id": "123456",
    "network": "ETH",
    "tx_url": "https://etherscan.io/tx/0x4fd6f1e67f2b4abbff4216138d1aeebfd4a56d8f05d05f0ad43550bfbaf41bb1",
}
```

## `POST` Payment TIMEOUT event

As an example, here you can see how a payment TIMEOUT looks like:

### Headers

```
{
    'Content-Type': 'application/json', 
    'X-API-KEY': 'api_key'
}
```

### Body

```json
{
    "payment_id": "6b577835afbefe60335b6e5cd04410a9",
    "status": "TIMEOUT",
    "processed_at": 1726248785,
    "foreign_id": "123456"
}
```

Mostly, the payload differs on the payment status, you can see the possible payment statuses [here](https://docs.ivpay.io/start/concepts#the-payment-statuses).

For successful webhook requests, a response with an HTTP status 200 is required. Any other status code or failure to respond will be treated as an error.